Roll API key
Mints a new API key and parks the current one as a previous key with its
own grace window (default 48 hours). The previous key remains valid until
its expires_at, so deployments can rotate credentials without downtime.
Security
The api_key must be supplied in the request body. Passing it as a
query-string parameter returns 400 — query-string credentials leak into
access logs, CDN logs, browser history, and Referer headers, which is
unacceptable on a credential-minting endpoint.
Rate limiting
Rolls are rate-limited per user. If you roll too frequently the response
is 429 with a Retry-After header and a retry_after_seconds field in
the JSON body.
Request
Your current API key. Must be supplied in the request body.
Passing it via query string returns 400 — query-string credentials
leak into access logs, CDN logs, browser history, and Referer headers.
Grace period (in hours) for the rolled-away key before it expires. Defaults to 48 hours and is clamped to a maximum of 48 hours.
Response
New API key minted; previous key parked with its grace window.
The newly-minted API key. Store this — plaintext is not returned again.
Recommended rotation date for the new key — two months after the roll. It is a reminder, not an expiry: the key keeps working after this date until you roll it.
When the just-parked previous key will stop being accepted.