Skip to content

Rotate a key

Replace a key's secret on a schedule, when someone leaves, or after a leak. The old and new secrets both work for a grace period you choose, so every caller can switch over with no failed call. Everything that belongs to the key stays with it: models, rate limit, routing, exemptions, guardrails and budgets.

Before you start

You hold the key, own the agent it belongs to, or are an admin over it.

Steps

  1. Open Keys and choose the key.
  2. Choose Replace secret.
  3. Choose how long the old secret keeps working: No time: it stops now, 1 hour, 1 day, 3 days or 7 days. After a leak, choose No time: it stops now: anything still using the old secret is refused at once.
  4. Optionally give a reason; it's kept with the rotation in the audit log.
  5. Confirm, and copy the new secret. It stays on screen until you choose Done.
  6. Put the new secret wherever the old one was used.

Replacing a key's secret with a one-day grace period, step by step

Check it worked

While the old secret works, the key says Old secret works until …, with when the old secret was last used, or Not used since the rotation. Once callers have moved, choose Stop old secret now: the gateway refuses the old secret within seconds, and the audit log records "Old secret stopped early".

Need more time? Extend old secret… gives it a later day, within the longest grace your organisation allows.

Good to know

  • The grace period is at most 7 days unless an organisation admin sets another limit (1 to 90 days) in key defaults.
  • Calls on either secret during the grace period are charged the same way.
  • Old secret last used can show a use from just before the rotation: check it against when you replaced the secret.
  • A program can also replace its own key's secret, once whoever manages the key turns on Let this key rotate its own secret on the key's page (never on an organisation admin's key). See Let a service rotate its own key.
  • Home's Needs attention offers Replace on a key that expires soon.