Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.footstep.ai/llms.txt

Use this file to discover all available pages before exploring further.

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.
The MCP server also accepts the standard Authorization: Bearer <key> form for compatibility with MCP SDKs whose default is Bearer authentication. Either header is fine; x-api-key is the recommended form across all Footstep surfaces.
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 and your account balance on every request:
StateHTTP statusError messageWhat to do
Active200-Key is working normally
Insufficient balance402Insufficient balance. Please top up your account.Top up your account at console.footstep.ai. The key itself is fine — only the balance is blocking the request
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 402 means the key is valid and active but your account has no credit — top up to resume requests. 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.