Authentication

Authenticate every request with an API key, understand which partner it acts for, and handle 401 and 403 errors.

Send your API key

Every request to /consumer/v1 and /partner/v1 carries your API key as a bearer credential:

curl -s "$VOUCHER_API_BASE_URL/partner/v1/principal" \
  -H "Authorization: Bearer $VOUCHER_API_KEY"

• 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.

Status	errorCode	Meaning	What to do
401	unauthenticated	No credential was sent	Send Authorization: Bearer <key>
401	token-invalid	The header is malformed or uses an unknown scheme	Check the header format
401	api-key-invalid	The key is unknown, revoked, expired, past its roll grace period or from the other environment	Check the key and the base URL; create or roll a key
403	partner-offboarded	Your partner was offboarded	Contact AllRide
403	partner-suspended	Your partner is suspended and the request is a write	Contact AllRide
403	api-access-inactive	API access is not active, or the partner is not active	Request API access or contact AllRide
403	ip-not-allowed	The source address is not on your IP allowlist	See IP allowlist
403	missing-permission	The key’s scopes lack a permission of the operation; more.requiredPermissions lists them	See Permissions and scopes
403	partner-role-missing	Your partner lacks the consumer role this surface needs	Use the surface of your partner’s role

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.

{
  "errors": [
    {
      "message": "The API key is unknown, revoked, expired, past its roll grace period or belongs to the other environment.",
      "statusCode": 401,
      "errorCode": "api-key-invalid"
    }
  ]
}

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.

Related

• API keys
• Permissions and scopes
• Errors