Skip to main content
POST
Rotate API Key

Overview

Rotates an existing API key by creating a new key with a new ID and the same name, scopes, rate limit tier, and metadata. The old key remains valid for a fixed 24-hour grace period to allow zero-downtime credential rotation in distributed systems. If the old key had a customer-set expiry sooner than 24 hours away, that earlier expiry is kept; rotation never extends a key’s life. The new key (including its new ID and secret) is returned only once in the response. Store it securely immediately. Requires the api-keys:manage scope, and the caller must hold every scope of the key being rotated. This endpoint requires an Idempotency-Key header; see Idempotency. Retrying with the same key replays the cached response, including the same rotated secret, so an ambiguous network failure never rotates twice.
The grace period is fixed at 24 hours and is not configurable. The old key automatically stops working 24 hours after rotation, and a key in its grace period cannot be rotated again.

Path Parameters

id
string
required
API key ID to rotate (e.g. key_Mc2eF6gH).

Response

Returns the new API key object, flat at the top level, with the same fields as Create API Key including the one-time key secret. The id, prefix, key, and created_at all belong to the new key; the name, scopes, rate_limit_tier, and metadata are inherited from the rotated key.

Code Examples

Errors