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

# API keys

> Create, scope, rotate and revoke API keys.

## Create a key

Keys are created in the developer dashboard under [API keys](https://provider-developers.voucher.allride.io/go/api-keys) by a member who holds `manage-api-keys`. An API key cannot create keys: the key operations under `/partner/v1/api-keys` accept only signed-in dashboard users, who must have signed in within the last 15 minutes. Keys can be created only while API access is `active`, and a partner can have at most 20 active keys.

When you create a key you choose:

* a **name** (1-80 characters), for example the system that uses it;
* its **scopes** (see below);
* an optional **expiry**, at most 2 years ahead (the dashboard suggests one year).

The secret is shown **once**. Afterwards only `name`, `keyHint`, `last4`, `scopes`, `expiresAt`, `lastUsedAt` and `lastUsedIp` are visible. If a create response is lost, a retry with the same `Idempotency-Key` returns `"secret": null` with `Idempotent-Replay-Redacted: true`: revoke that key and create a new one.

## Key format

```text theme={null}
vk_<environment>_<keyId>_<secret>
vk_test_…   sandbox
vk_live_…   production
```

The full format is `^vk_(live|test)_[0-9a-hjkmnp-tv-z]{26}_[0-9A-Za-z]{43}$`. Add this pattern to your secret scanners. Treat the whole string as a password.

## Scopes

Scopes are permissions delegated to the key. A key can only receive:

* permissions that are **delegable** (see the [permission reference](https://docs-provider.voucher.allride.io/guides/permissions.md#permission-reference)); others → 422 `scope-not-delegable`;
* permissions that apply to your partner's roles; others → 422 `permission-not-applicable`;
* permissions that the creating user holds; others → 403 `missing-permission`.

Scopes cannot be changed later. To change them, create a new key or roll this one and revoke it.

## Rotate a key

Roll the key in the dashboard (`POST /partner/v1/api-keys/{apiKeyId}:roll` with `gracePeriodMinutes`, 1 to 10,080, default 1,440):

1. AllRide creates a **new** key with the same scopes and returns its secret once.
2. Both keys work until the grace period ends; then the old key gets 401 `api-key-invalid`.
3. Deploy the new secret within the grace period and check that `lastUsedAt` of the new key moves.

The rolled key shares the old key's idempotency scope, so a request retried with the new key and the same `Idempotency-Key` replays instead of running twice.

Without a grace window you can also rotate manually: create a new key, deploy it, check `lastUsedAt`, then revoke the old key. A new independent key has its own idempotency scope; finish in-flight retries before you switch.

## Revoke a key

Revoke a key in the dashboard (`POST /partner/v1/api-keys/{apiKeyId}:revoke`). It stops working on every server within 60 seconds and cannot be reactivated. Revoke at once if a key may have leaked, then check the [audit log](https://docs-provider.voucher.allride.io/workspace/audit-log.md) for its actions.

## Store keys safely

* Keep keys in a secret manager and inject them at runtime; never commit them.
* Use one key per system and environment, so you can revoke one without affecting others.
* Never send a key to a browser, a mobile app or a third-party service.
* Restrict where keys can be used from with the [IP allowlist](https://docs-provider.voucher.allride.io/guides/ip-allowlist.md).
* Never log the `Authorization` header.

## Related

* [Authentication](https://docs-provider.voucher.allride.io/guides/authentication.md)
* [Permissions and scopes](https://docs-provider.voucher.allride.io/guides/permissions.md)
* [Idempotency](https://docs-provider.voucher.allride.io/guides/idempotency.md#key-scope-and-key-rotation)


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