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

# Authentication

> Authenticate API requests with your partner API key.

## Send your API key

Send the key in the `Authorization` header of every request:

```bash theme={null}
curl -sS "$VOUCHER_API_BASE_URL/partner/v1/principal" \
  -H "Authorization: Bearer $VOUCHER_API_KEY"
```

* 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](https://docs-provider.voucher.allride.io/errors/catalog.md#partner-role-missing)). `/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:

| Situation | Response |
| - | - |
| API access not active (requested, declined, suspended) | 403 `api-access-inactive` |
| Partner suspended, write request | 403 `partner-suspended` |
| Partner suspended, read request | 403 `api-access-inactive` |
| Partner offboarded | 403 `partner-offboarded` |

`GET /partner/v1/api-access` and the [API access page](https://provider-developers.voucher.allride.io/go/api-access) show the current state and any decision reason.

## When authentication fails

| Status and code | Cause | What to do |
| - | - | - |
| 401 `unauthenticated` | No `Authorization` header | Send the key |
| 401 `token-invalid` | Unknown scheme, malformed value, two headers | Send `Bearer <key>` once |
| 401 `api-key-invalid` | Unknown, revoked or expired key, or a key of the other environment | Check the key and the base URL; create or roll a key |
| 403 `api-access-inactive` | API access or partner not active | Request access; contact AllRide |
| 403 `ip-not-allowed` | Request from outside your [IP allowlist](https://docs-provider.voucher.allride.io/guides/ip-allowlist.md) | Call from an allowed address |
| 403 `missing-permission` | The key lacks a scope; `more.requiredPermissions` names it | Create a key with that scope |

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](https://docs-provider.voucher.allride.io/guides/permissions.md#choosing-scopes).
* Keep keys in a secret manager; rotate them on a schedule with [`:roll`](https://docs-provider.voucher.allride.io/guides/api-keys#rotate-a-key).
* Always call over HTTPS, and turn on the [IP allowlist](https://docs-provider.voucher.allride.io/guides/ip-allowlist.md) 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.

## Related

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


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