Rotate a key safely

Rotating issues a successor carrying the same label, scopes, limits and sender, and puts the old key on a clock. Both work until the clock runs out, so you can deploy the new secret without a window where requests fail.

Rotate from the dashboard, under Settings → Console → API keys, choosing a grace period. There is no /v1 endpoint for this — an API key cannot rotate itself.

Rotating without downtime

  1. Rotate with a grace period long enough to cover a deploy. An hour is generous; the default is 60 minutes and the maximum is 7 days.
  2. Copy the new secret. It is shown once.
  3. Update your config and deploy.
  4. Confirm traffic is flowing on the new key.
  5. Do nothing else — the old key expires on its own.

When a key has leaked

Rotate with a grace period of zero. The old secret stops working immediately, so your integration fails until you deploy the new one — the right trade when the secret is public.

What cannot be rotated

  • A deleted key.
  • An expired key.
  • A key already counting down from an earlier rotation.

In all three cases, create a new key instead.

Two things to get right

Read the key from the environment, not from your source. Rotating is a config change; if the secret is in code, it is also a code change and a review and a release.

Rotate on a schedule, not only after an incident. A rotation you have practised is a rotation that works under pressure.

Per-customer keys

If you issue a key per customer, rotate one without touching the others. That is most of the reason to issue them separately — see One key per customer.