Skip to main content

​
Send your API key

Send the key in the Authorization header of every request:
  • HTTPS only, TLS 1.2 or newer. Plain-HTTP requests to the API host are refused with 403 and never redirected.
  • Never put a key in a query string, a request body, a browser or a mobile app. Keys belong to server-to-server calls.
  • Send exactly one Authorization header. A missing credential is 401 unauthenticated; a malformed one or two headers are 401 token-invalid.

​
Partner context

An API key belongs to one partner, and every request with it acts for that partner. There is no header to choose a partner: the API ignores an X-Partner-Id header. To work for several partners, use one key per partner. Every resource you address must belong to your partner. An id of another partner answers exactly like an unknown id: 404 with the resource’s …-not-found code. /provider/v1 needs a partner with the provider role; a consumer-only partner gets 403 partner-role-missing with more.requiredRole: "provider" (catalog). /partner/v1 serves every partner. The dashboards use the same API with the signed-in user’s ID token instead of a key; they do not accept API keys, and the API does not accept dashboard sessions from your backend.

​
API access activation

API keys authenticate only while both are true:
  1. Your partner’s API access is active. You request it once in the developer dashboard; AllRide activates it (states not-requested → requested → active, and suspended if AllRide suspends it).
  2. Your partner is active.
Otherwise a valid key gets 403: GET /partner/v1/api-access and the API access page show the current state and any decision reason.

​
When authentication fails

The checks run in this order: credential, partner status and API access, IP allowlist, permissions. Every 401 carries WWW-Authenticate: Bearer realm="voucher". Revoking a key takes effect within 60 seconds.

​
Security recommendations

  • One key per system and environment, with the minimum scopes.
  • Keep keys in a secret manager; rotate them on a schedule with :roll.
  • Always call over HTTPS, and turn on the IP allowlist for API keys.
  • Watch lastUsedAt and lastUsedIp of your keys and revoke unused ones.
  • Add the key format to your secret scanners so a leaked key is found early.