Rotate API Key
API Keys
Rotate API Key
Rotate an existing API key, generating a new secret
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 theapi-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
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-timekey 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
Related Endpoints
- List API Keys, view all keys
- Create API Key, generate a new key
- Delete API Key, immediate revocation