> ## Documentation Index
> Fetch the complete documentation index at: https://docs-consumer.voucher.allride.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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`](https://docs-consumer.voucher.allride.io/api-reference/partner-principal-get) 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`](https://docs-consumer.voucher.allride.io/errors/catalog#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](https://consumer-developers.voucher.allride.io/go/api-access) ([`POST /partner/v1/api-access:request`](https://docs-consumer.voucher.allride.io/api-reference/partner-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`](https://docs-consumer.voucher.allride.io/api-reference/partner-api-access-get) 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`](https://docs-consumer.voucher.allride.io/errors/catalog#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`](https://docs-consumer.voucher.allride.io/errors/catalog#unauthenticated) | No credential was sent | Send `Authorization: Bearer <key>` |
| 401 | [`token-invalid`](https://docs-consumer.voucher.allride.io/errors/catalog#token-invalid) | The header is malformed or uses an unknown scheme | Check the header format |
| 401 | [`api-key-invalid`](https://docs-consumer.voucher.allride.io/errors/catalog#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`](https://docs-consumer.voucher.allride.io/errors/catalog#partner-offboarded) | Your partner was offboarded | Contact AllRide |
| 403 | [`partner-suspended`](https://docs-consumer.voucher.allride.io/errors/catalog#partner-suspended) | Your partner is suspended and the request is a write | Contact AllRide |
| 403 | [`api-access-inactive`](https://docs-consumer.voucher.allride.io/errors/catalog#api-access-inactive) | API access is not `active`, or the partner is not `active` | Request API access or contact AllRide |
| 403 | [`ip-not-allowed`](https://docs-consumer.voucher.allride.io/errors/catalog#ip-not-allowed) | The source address is not on your IP allowlist | See [IP allowlist](https://docs-consumer.voucher.allride.io/guides/ip-allowlist.md) |
| 403 | [`missing-permission`](https://docs-consumer.voucher.allride.io/errors/catalog#missing-permission) | The key's scopes lack a permission of the operation; `more.requiredPermissions` lists them | See [Permissions and scopes](https://docs-consumer.voucher.allride.io/guides/permissions.md) |
| 403 | [`partner-role-missing`](https://docs-consumer.voucher.allride.io/errors/catalog#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.

```json theme={null}
{
  "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](https://docs-consumer.voucher.allride.io/guides/permissions.md)).
* Give keys an expiry and rotate them at least every 12 months with `:roll` ([API keys](https://docs-consumer.voucher.allride.io/guides/api-keys.md)).
* Turn on the [IP allowlist](https://docs-consumer.voucher.allride.io/guides/ip-allowlist.md) 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](https://consumer-developers.voucher.allride.io/go/api-keys) and tell AllRide.

## Related

* [API keys](https://docs-consumer.voucher.allride.io/guides/api-keys.md)
* [Permissions and scopes](https://docs-consumer.voucher.allride.io/guides/permissions.md)
* [Errors](https://docs-consumer.voucher.allride.io/errors.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.