Skip to main content

​
Send your API key

Every request to /consumer/v1 and /partner/v1 carries your API key as a bearer credential:
  • Send the key only in the Authorization: Bearer header. Keys in query strings, request bodies or other headers are ignored, so such a request counts as unauthenticated.
  • The API is HTTPS only, with TLS 1.2 or newer. There is no plain-HTTP listener and no redirect from HTTP.
  • Sandbox keys start with vk_test_ and work only against https://api.voucher-staging.allride.io; production keys start with vk_live_ and work only against https://api.voucher.allride.io.
GET /partner/v1/principal tells you which partner, environment and permissions a key has. Use it as a health check when you deploy a new key.

​
Partner context

An API key belongs to exactly one partner, and every request made with it acts for that partner. There is no header to choose a partner: a request can never read or change another partner’s data, and an id that belongs to another partner answers 404 as if it did not exist. /consumer/v1 requires a consumer partner. A key of a partner that is only a provider gets 403 partner-role-missing. /partner/v1 is shared by providers and consumers; a few of its operations (SMTP configuration, email templates and custom domains) are consumer-only. The consumer dashboard calls the same API, but with the signed-in user’s Firebase ID token instead of an API key. Some operations that change security or billing settings, or accept prices, are reserved for those dashboard users; the API reference marks them “Dashboard session only. API keys cannot call this operation.”

​
API access activation

API keys work only while your partner’s API access is active. AllRide activates it:
  1. A user with the request-api-access permission requests it in the developer dashboard (POST /partner/v1/api-access:request).
  2. AllRide reviews the request and activates API access, or declines it with a reason. You get an email either way.
  3. Once active, members with manage-api-keys can create keys.
GET /partner/v1/api-access shows the status: not-requested, requested, active or suspended. AllRide can suspend API access; while it is not active, every API-key request is refused with 403 api-access-inactive. Your partner itself must also be active.

​
When authentication fails

The API checks the credential first, then a fixed sequence of gates. The first failing check answers. An unknown, revoked or expired key always gets the same api-key-invalid answer, so the response never reveals whether a key exists. A revoked key stops working within 60 seconds.
Every 401 also carries the header WWW-Authenticate: Bearer realm="voucher". Do not retry authentication errors in a loop: fix the key or the configuration first.

​
Security recommendations

  • Keep keys in a secret manager and inject them at runtime; never commit them, put them in client apps or browsers, or log them. Add the key pattern ^vk_(live|test)_[0-9a-hjkmnp-tv-z]{26}_[0-9A-Za-z]{43}$ to your secret scanners.
  • Use one key per system and environment, with the minimum scopes that system needs (Permissions and scopes).
  • Give keys an expiry and rotate them at least every 12 months with :roll (API keys).
  • Turn on the IP allowlist for your API keys.
  • Call the API only from your backend. The API does not serve browsers other than the AllRide dashboards.
  • If a key leaks, revoke it immediately in the developer dashboard and tell AllRide.