Skip to content
← Changelog
2.2.130
Feature

Stop deleting API keys to rotate them

Replacing a personal API key by hand loses its settings, and deleting the old one breaks every client that still holds it; now it is one step, and the old key keeps working for up to 7 days.

We built Rotate key to make the replacement for you. The new key carries the old key's models, limits and permissions, and the old key keeps working for up to 1 hour, 1 day or 7 days, as you choose, or stops at once if you choose Now. With an overlap, your clients can switch without a gap.

To start, open API Keys in your settings, open the menu on the key's row and choose Rotate key.

Choose how long the old key keeps working

The Rotate dialog for a key named default: a name for the new key, and the choices Now, 1 hour, 1 day and 7 days with 1 day selected
Choiceold_key_expires_inThe old key
Now0is revoked in the same step, and requests with it are refused at once
1 hour3600keeps working for 1 hour, then expires
1 day (default)86400keeps working for 1 day, then expires
7 days604800keeps working for 7 days, then expires

If the old key already had an expiry that comes sooner, that earlier time stays. Until it stops, the old key keeps its name, its settings and its usage history. Choosing Now asks you to confirm first, because a revoked key cannot be enabled again (2.2.122).

What the new key copies

New key
Allowed models and IP allowlistcopied
Fallback models and timeout, compression settingscopied
Permission mode and restricted permissionscopied
Monthly limit and spend limit per hourcopied
Expirycopied
Creditstarts with the credit the old key had left; unlimited stays unlimited
Usage countersstart at zero
Namethe one you give it, different from every key you have that is not revoked
Statusenabled, even when the old key was disabled

While both keys work, they share the old key's one share of your account's monthly limit, so a key that holds the whole limit can still be rotated. Once the old key stops, it holds no share of it. The old key keeps its own credit until it stops.

The new key's secret is shown once, when it is made. Copy it before you close the dialog. Afterwards, unless you chose Now, the key list shows both keys, with the time the old one stops in its Expires column.

The API Keys list after rotating: default (new) never expires, and default stays active until Nov 20, 2026

A rotation is written to your account's activity log.

The call the dashboard makes

Rotate key is one request. It is an account call, authenticated as you (your signed-in session or your account access token); an API key is not accepted.

POST /api/token/{id}/rotate
Content-Type: application/json

{"name": "default (new)", "old_key_expires_in": 86400}
FieldType
namestringrequired; the new key's name, 1 to 30 characters
old_key_expires_inintegeroptional; 0, 3600, 86400 or 604800 seconds, 86400 when omitted

The response is sent with Cache-Control: no-store. data is the new key in the shape the key list uses, with more fields, including its permissions and limits (not shown here), plus key, the full secret, which no later response returns:

{
  "success": true,
  "message": "",
  "data": {
    "id": 4182,
    "tracking_id": "key_4182",
    "name": "default (new)",
    "key": "sk-apx_<46 characters>",
    "key_masked": "sk-...a9Zq",
    "secret_viewable": false,
    "status": "active",
    "expires_at": null
  }
}

A refused rotation changes nothing: no key is made and the old key is untouched. Refusals from the rotation itself use one envelope, {"success": false, "code": "...", "message": "..."}:

StatuscodeWhen
400invalid_idthe id in the path is not a positive integer
400invalid_requestthe body is not valid JSON
400name_requiredname is missing
400invalid_namethe name is blank or longer than 30 characters
400invalid_old_key_expires_inthe value is not one of the four
400invalid_monthly_limitthe new key's monthly limit does not fit your account's monthly limit
404not_foundno key of yours has that id; an organization's key answers the same
409name_takena key of yours that is not revoked already has that name, the old key's own name included
409token_revokedthe key is revoked
409token_expiredthe key has expired
409token_changedthe key's monthly limit changed while it was being rotated; try again
403subscription_tokenthe key belongs to a subscription plan
403email_change_cooldownthe account's email address was changed a short while ago

A request from a session that must confirm its sign-in first is refused with 401 fresh_auth_required. Requests over the rate limit answer 429.

Also in this entry

Every key you create is shown once. A key you create now is shown in full when it is created or rotated, and not again. After that the key list shows sk-... and its last four characters, and a request to reveal it answers 409 secret_not_viewable. A key made before this change can still be copied from its row after you confirm your sign-in, and the default key made at sign-up and your subscription plan key stay viewable.

A monthly ceiling for auto-reload. In Credits, the auto-reload settings have a new field, Monthly limit (optional), in US$. It is empty by default, which means no limit, and when set it must be at least the reload amount. When the reloads already made in a calendar month (UTC) plus the next one would pass it, that reload is skipped and no charge is attempted. Reloads start again with the next month.

Per-key spend limits have their own entry: see "Set limits that bound a leak" in 2.2.122. A rotated key keeps its spend limit per hour, monthly limit, allowed models and IP allowlist; its credit limit is what the old key had left.