Skip to main content
API keys authenticate your backend systems. Each key belongs to one partner and one environment and carries a fixed set of permissions, its scopes.
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 (or with POST /partner/v1/api-keys 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);
  • fewer than 20 active keys in your partner (else 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

  • 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:
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 (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.
  • You can only grant permissions you hold yourself; otherwise the request is refused with 403 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.

​
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 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.
  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). 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 (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.