Skip to main content
Every request to the Footstep API must include an API key. This page explains how keys work, what happens when authentication fails, and how to keep your keys secure.

​
How it works

Pass your API key in the x-api-key header on every request. The API validates the key before processing. If it’s missing, malformed, or invalid, the request is rejected immediately. 
curl -X POST https://api.footstep.ai/v1/routing/route \
  -H "x-api-key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"locations": [{"lat": 51.5322, "lon": -0.1240}, {"lat": 51.5055, "lon": -0.0754}]}'

​
Key format

All API keys follow the format sk_live_* (e.g. sk_live_abc123def456). If the key you’re sending doesn’t start with sk_live_, the API will reject it with a 401. Create and manage keys at console.footstep.ai.

​
Key states

Keys can be in one of several states. The API checks the key’s state on every request:
StateHTTP statusError messageWhat to do
Active200—Key is working normally
Suspended403API key is suspendedContact support. Your key has been temporarily disabled
Revoked403API key has been revokedGenerate a new key in the console. Revoked keys cannot be reactivated
Not found403Invalid API keyCheck for typos. If correct, the key may have been deleted
Missing or malformed401Missing or invalid API key formatEnsure you’re sending the x-api-key header with a valid sk_live_* key
A 401 means the request had no valid key at all. A 403 means the key was recognised but isn’t allowed: it’s been suspended, revoked, or doesn’t exist.

​
Security best practices

API keys are for server-side use only. Never expose them in frontend code, mobile apps, or browser JavaScript. Anyone who has your key can make requests on your behalf.
  • Use environment variables. Store keys in FOOTSTEP_API_KEY or your platform’s secret manager, not in source code.
  • Never include keys in query strings. Query strings appear in server logs, browser history, and CDN caches. Always use the x-api-key header.
  • Rotate keys regularly. Generate a new key in the console, update your services, then revoke the old one.
  • Use separate keys per environment. Different keys for development, staging, and production make it easier to rotate and audit.
  • Restrict access. Only share keys with services that need them. If a key is compromised, revoke it immediately and generate a replacement.