Skip to content
ApiqDevelopers
API v1.64.0Open console
API referenceidentity

Rotate api key

POST/v1/keys/{keyPrefix}/rotate
Accepts X-Api-Key · oauthClientCredentials · bearer

Rotate an API key with an overlap window

Mints the replacement — same name, scopes and allowlist, its secret shown once here — and keeps the old key working until overlapUntil (default 24h, at most 7d), its calls carrying a Deprecation…Show moreMints the replacement — same name, scopes and allowlist, its secret shown once here — and keeps the old key working until overlapUntil (default 24h, at most 7d), its calls carrying a Deprecation header and a Sunset naming when it stops. After that the old key is refused. A key already rotating, or revoked, is a 409: rotate the replacement. the successor carries the parent's whole scope — kind, writes, products, the caps, principal, agent and mintedBy — with expiresAt = min(now + the key's lifetime, the minting key's expiresAt), so a child never outlives its parent; the old key's successorKeyPrefix names it, and after overlapUntil the old key reads state EXPIRED. A key with an expiresAt rotated by itself or by a Member session may rotate only within 7 days of it, else 409 CONFLICT details.reason ROTATION_TOO_EARLY (details.expiresAt); an Owner or Admin session may rotate at any time (an emergency rotation). The key itself (an API key presenting its own keyPrefix) may rotate itself while the flag is on; any other key is 404. Emits key.rotated. MCP: unchanged, excluded.

Path parameters

  • keyPrefixstringRequired

Request body

This operation takes no request body.

Responses

  • 201The replacement, and until when the old key still worksRotatedApiKey
  • 401
    UNAUTHENTICATED — missing or expired token.Show moreUNAUTHENTICATED — missing or expired token. Declared on every operation because `security` is declared globally at the document root: every route is authenticated, so every route can answer 401.
    ApiErrorResponse
  • 403
    The 403s of the credential-issuing routes (POST /v1/keys, POST /v1/keys/{keyPrefix}/rotate, POST /v1/invites).Show moreThe 403s of the credential-issuing routes (POST /v1/keys, POST /v1/keys/{keyPrefix}/rotate, POST /v1/invites). PERMISSION_DENIED when the caller lacks keys:manage / users:manage, and on the key routes also when a live key is asked for a tenant that is not LIVE or is a sandbox twin. On POST /v1/keys also PERMISSION_DENIED with details.reason SYSTEM_KEY_REQUIRES_ADMIN when actorKind is system and the caller is not a tenant admin.
    ApiErrorResponse
  • 404NOT_FOUND — unknown or expired ref (unguessable refs, 15)ApiErrorResponse
  • 405
    VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge).Show moreVALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge). Not retryable as sent.
    ApiErrorResponse
  • 409
    State conflict, as components/responses/Conflict: CONFLICT when the key is already rotating or is revoked; also CONFLICT details.reason ROTATION_TOO_EARLY for a key with an expiresAt more than 7 days…Show moreState conflict, as components/responses/Conflict: CONFLICT when the key is already rotating or is revoked; also CONFLICT details.reason ROTATION_TOO_EARLY for a key with an expiresAt more than 7 days away, rotated by itself or a Member session (never an Owner or Admin session).
    ApiErrorResponse
  • 414
    VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge).Show moreVALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge). Not retryable as sent: send long input in the body of a POST.
    ApiErrorResponse
  • 423
    PERMISSION_DENIED with details.reason KEY_PAUSED: the API key is PAUSED and every call with it is refused until an Owner or Admin resumes it (POST /v1/keys/{keyPrefix}:resume, a person only); or…Show morePERMISSION_DENIED with details.reason KEY_PAUSED: the API key is PAUSED and every call with it is refused until an Owner or Admin resumes it (POST /v1/keys/{keyPrefix}:resume, a person only); or details.reason LOOP_DETECTED on the call whose loop paused the key (20 identical requests in 60 s, or 50 holds without a booking or release in 10 min; replays of one Idempotency-Key never count). Not retryable; nextAction stop — the agent stops using the key and tells the person; details carry resumeBy (owner), consoleLink and evidence (ApiKeyPauseEvidence). Nothing was charged, held or sent; holds and orders already made are untouched. A key whose ancestor (the key that minted it, or that key's minter) is PAUSED answers the same 423 KEY_PAUSED, and resuming the ancestor resumes it, so a child never outlasts a pause of its parent. The MCP plane answers the identical body as an isError result. Any key-authenticated route may answer it; it is declared on the order and hold writes, search, reprice and the key routes.
    ApiErrorResponse
  • 429
    RATE_LIMITED with details.reason VELOCITY_LIMIT: a soft breach of the API key's own scope (reqPerSec, holdsPerHour, cancelsPerDay, lookToBook, spendPerDay) — the first two in 24 hours; the third, or a…Show moreRATE_LIMITED with details.reason VELOCITY_LIMIT: a soft breach of the API key's own scope (reqPerSec, holdsPerHour, cancelsPerDay, lookToBook, spendPerDay) — the first two in 24 hours; the third, or a burst above 5× the limit, pauses the key instead (423 KeyPaused). Retryable after retryAfterMs (mirrored by Retry-After); nextAction slow_down; details carry limit, windowSeconds and the dimension in details.field. The tenant quota of RateLimited and the key's velocity are separate limits. Every call of a minted key also counts against each ancestor key's velocity and spend windows, so minting N children never multiplies the blast radius; spendPerDay is reserved atomically before the order is placed and released if it fails.
    ApiErrorResponse
  • 500INTERNAL — a bug, and traceId is the support handle.ApiErrorResponse

Errors you should handle

Branch on code and honour retryable — never on the HTTP status alone.

401UNAUTHENTICATED
The bearer token is expired. Re-authenticate and retry.
not retryable
403PERMISSION_DENIED
Inviting colleagues needs the users:manage permission.
not retryable
403TENANT_SUSPENDED
This tenant is suspended; no key can be minted or rotated until it is reinstated. Existing keys can still be revoked.
not retryable
404NOT_FOUND
searchRef SR-F-7b31d0a9 is unknown or has expired; re-search
not retryable
405VALIDATION
This method is not served.
not retryable
409CONFLICT
The order is in a state that does not allow this transition
not retryable
409OFFER_EXPIRED
offerRef OF-H-8c1f4a2e expired at 2026-09-14T17:34:11Z; re-reprice
not retryable
409HOLD_EXPIRED
holdRef HD-M-4419ab expired at 2026-09-14T17:05:41Z; the seats were released
not retryable
409IDEMPOTENCY_CONFLICT
Idempotency-Key 7f0c33d1-9a1e-4d2c-9f77-1c0f2b3a4d55 was used with a different body; never executed
not retryable
414VALIDATION
The request URI is longer than 8 KiB.
not retryable
423PERMISSION_DENIED
This API key is paused: 212 holds in 9 min. An Owner or Admin must resume it in the console.
not retryable
429RATE_LIMITED
This API key exceeded its rate: 10 requests a second. Retry after 1.2 s.
retryable
500INTERNAL
An unexpected error occurred. Quote the traceId to support.
retryable