Skip to main content

​
Create a key

Keys are created in the developer dashboard under 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

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); 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 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.
  • Never log the Authorization header.