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

# API keys

> Create API keys with the right scopes, recognise their format, rotate them without downtime and revoke them.

API keys authenticate your backend systems. Each key belongs to one partner and one environment and carries a fixed set of permissions, its **scopes**.

> [!WARNING]
>
> Use the API playground on these docs only with sandbox `vk_test_` keys. Playground requests are sent from Mintlify's servers, so they fail when your sandbox IP allowlist is enforced.

## Create a key

Keys are created only by signed-in users in the [developer dashboard](https://consumer-developers.voucher.allride.io/go/api-keys) (or with [`POST /partner/v1/api-keys`](https://docs-consumer.voucher.allride.io/api-reference/partner-api-keys-create) and a dashboard session). An API key can never create, roll or revoke keys.

You need:

* the permission `manage-api-keys` (the owners, administrators and developers groups have it) and a sign-in within the last 15 minutes;
* API access in status `active` ([Authentication](https://docs-consumer.voucher.allride.io/guides/authentication.md#api-access-activation));
* fewer than 20 active keys in your partner (else [`api-key-limit-reached`](https://docs-consumer.voucher.allride.io/errors/catalog#api-key-limit-reached)).

A key has a `name` (1-80 characters), its `scopes` and an optional `expiresAt` of at most 2 years ahead. The dashboard suggests one year.

**The secret is shown once**, in the response to the create call. Copy it into your secret manager straight away. Afterwards the API and the dashboard show only the key's metadata: `name`, `keyHint`, `last4`, `scopes`, `status`, `expiresAt`, `lastUsedAt` and `lastUsedIp`. If you lose the secret, create a new key.

If the create response is lost (for example a timeout) and you retry with the same `Idempotency-Key`, the replayed response has `"secret": null` and the header `Idempotent-Replay-Redacted: true`. The key was created, but its secret cannot be shown again: revoke that key and create a new one.

Owners of your partner and your technical contact receive an email whenever a key is created or rolled, and before a key expires.

## Key format

```text theme={null}
vk_<environment>_<key id>_<secret>
```

* `environment` is `live` (production) or `test` (sandbox).
* `key id` is 26 lower-case Crockford base32 characters that identify the key.
* `secret` is 43 base62 characters.

The complete pattern is:

```text theme={null}
^vk_(live|test)_[0-9a-hjkmnp-tv-z]{26}_[0-9A-Za-z]{43}$
```

Add it to your secret scanners (for example as a custom pattern in your repository's secret scanning) so that a committed key is caught.

## Scopes

Scopes are the permissions the key may use. They are fixed when you create the key; to change them, create a new key.

* Choose only **delegable** permissions. The permissions marked "no" in the [permission reference](https://docs-consumer.voucher.allride.io/guides/permissions.md#permission-reference) (for example `manage-api-keys`, `manage-consumer-billing` and `accept-consumer-pricing`) can never be scopes: a create request with one is refused with `422` [`scope-not-delegable`](https://docs-consumer.voucher.allride.io/errors/catalog#scope-not-delegable).
* You can only grant permissions you hold yourself; otherwise the request is refused with `403` [`missing-permission`](https://docs-consumer.voucher.allride.io/errors/catalog#missing-permission).
* A request made with the key uses only the key's scopes, never the permissions of the user who created it.

Typical consumer integrations use `view-consumer-catalog`, `create-consumer-redemptions`, `view-consumer-redemptions`, `manage-consumer-redemption-entities` and `erase-consumer-redemption-entities`; an ERP integration for invoices uses `view-consumer-billing`. See [Choosing scopes](https://docs-consumer.voucher.allride.io/guides/permissions.md#choosing-scopes).

## Rotate a key

Rotate keys regularly (at least every 12 months) and whenever someone who had access to a secret leaves.

**Roll (recommended).** [`POST /partner/v1/api-keys/{apiKeyId}:roll`](https://docs-consumer.voucher.allride.io/api-reference/partner-api-keys-roll) with a `gracePeriodMinutes` between 1 and 10,080 (default 1,440, that is 24 hours) creates a **new** key named `<old name> (rolled)` with the same scopes and returns its secret once (`201`). Both keys work during the grace period; afterwards the old key gets `401` [`api-key-invalid`](https://docs-consumer.voucher.allride.io/errors/catalog#api-key-invalid).

```json theme={null}
{
  "gracePeriodMinutes": 1440
}
```

1. Roll the key in the dashboard and store the new secret.
2. Deploy the new secret to your systems within the grace period.
3. Check `lastUsedAt` of the new key (and that the old key's `lastUsedAt` stops moving).

A rolled key keeps the idempotency scope of the key it replaces: a retry that you started with the old key and repeat with the new key and the same `Idempotency-Key` replays the stored response instead of redeeming twice ([Idempotency](https://docs-consumer.voucher.allride.io/guides/idempotency.md)).

**Manual rotation (no grace period).** Create a new key, deploy it, verify its `lastUsedAt`, then revoke the old key. A newly created key does **not** share the old key's idempotency scope, so do not switch keys in the middle of a retry: finish or reconcile open requests first.

## Revoke a key

Revoke a key in the dashboard or with [`POST /partner/v1/api-keys/{apiKeyId}:revoke`](https://docs-consumer.voucher.allride.io/api-reference/partner-api-keys-revoke) (optional `reason`, up to 500 characters, kept in your audit log). Revocation takes effect on every server within 60 seconds; the key then gets `401` `api-key-invalid`. A revoked key cannot be reactivated.

Revoke a key immediately when you suspect it leaked, and tell AllRide. AllRide can also revoke a key in an emergency and informs your partner owners when it does.

## Store keys safely

* Keep keys in a secret manager and inject them at runtime. Never commit them, embed them in mobile or browser apps, or put them in URLs.
* Do not log the `Authorization` header. If you need to identify a key in logs, log its `keyHint` or `last4`.
* Use one key per system and per environment, so that you can rotate or revoke one without affecting the others.
* Set an expiry and track it; you receive reminder emails 14 days and 1 day before a key expires.
* Restrict where keys can be used from with the [IP allowlist](https://docs-consumer.voucher.allride.io/guides/ip-allowlist.md).

## Related

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


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