Rotate an API key

POST/v1/projects/{projectId}/keys/{keyId}/rotate

This operation supports dashboard session-cookie authentication. Call it only from trusted server code; browsers must not manufacture or expose the session cookie.

Creates a replacement key with the same name and scopes and revokes the old key in the same transaction. Session-cookie auth only. Rate limit: 60 requests per 60 s per session.

SEND AN idempotencyKey. Without one, a rotation whose response never reaches you leaves you worse off than if you had never called: the old key is revoked, the replacement's secret exists nowhere, and retrying the same URL is refused with already_revoked. With one, the retry returns the SAME replacement and the same keyRaw, and rotates nothing a second time.

Error codes: unauthorized (401), invalid_body (400), not_found (404), already_revoked (409), idempotency_key_conflict (409), rotation_secret_expired (409), rotation_secret_unrecoverable (409), key_generation_failed (500).

Authentication

sessionCookie — Dashboard session cookie set by POST /v1/auth/login. Video and playback endpoints additionally require the projectId query parameter under cookie auth.

Parameters

Name	In	Type	Required	Description
`projectId`	path	string (Ulid)	Yes	—
`keyId`	path	string (Ulid)	Yes	—

Request body

optional

Content type: application/json

Schema: ApiKeyRotateRequest

{
  "idempotencyKey": "rotate-billing-key-2026-07-26T09:15:00Z"
}

Responses

Status	Meaning
`201`	Replacement key. Store `keyRaw` now; it is never shown again, and it is recoverable by an `idempotencyKey` retry for 10 minutes only.
`400`	The request body or query failed validation. The per-operation description lists the exact `error.code` values.
`401`	No valid credential was presented.
`404`	The resource does not exist or is not visible to this caller.
`409`	The request conflicts with the resource's current state. The per-operation description lists the exact `error.code` values.
`429`	Rate limit exceeded.
`500`	The server failed to complete the request.

Example request

{
  "idempotencyKey": "rotate-billing-key-2026-07-26T09:15:00Z"
}