Rotating Keys

Rotate in the portal

Open API keys and choose Rotate on the key. Pick an overlap (from "retire now" up to 7 days; the default is 24 hours) and transmute, in one step:

1. Mints a new key with the same name, environment, scopes, X-Api-Version pin and per-key rate limit, and copies its IP allowlist. The new secret is shown once — copy it into your secret manager.
2. Schedules the old key to retire at the end of the overlap. It keeps working until then (or until its own earlier expiry — rotation never extends a key's life), then answers unauthorized 401.

Deploy the new key within the overlap and confirm traffic flows. If you subscribed to the key.expiring webhook event, you are notified 7 days and 1 day before a key expires, including the retiring key.

Workspace admins and owners can rotate any key; members can rotate the keys they created. A key can be rotated once — to rotate again, rotate its successor. The same operation is available on the portal API: POST /v1/portal/keys/{id}/rotate with an optional {"overlap_hours": 0-168}.

Expiring keys

When you create a key you can set an expiry date (at most two years ahead). Expired keys are refused like revoked ones and no longer count toward the 20-key limit. Keys without an expiry never expire — put rotation on your own calendar; quarterly is a common cadence for payment infrastructure.

If a key has leaked

Don't rotate with an overlap. Revoke the leaked key immediately (revocation has no grace period), accept the brief outage, then create and deploy a replacement — or rotate with Retire the old key now. An exposed key that can convert your payment traffic is worse than a few minutes of 401s.

Making rotations painless

• Name keys by system. The successor keeps the name, and the keys list shows which key is retiring.
• One key per system. Rotating a shared key forces you to redeploy everything at once.
• Load the key from your secret manager at startup rather than baking it into images — then rotation is a secret update plus a restart, not a rebuild.

OAuth alternative

If your security posture requires short-lived credentials as a rule, use OAuth client credentials instead of long-lived keys: tokens expire after 15 minutes, and revoking the client stops new tokens immediately (outstanding tokens live out their ≤15-minute lifetime).