Rotate an API key

Rotate keys on a schedule (90 days is a reasonable default), immediately if a key is exposed, and whenever staff with access leave the team. Both keys remain valid until the old one is revoked, so the cutover window is whatever your deploy cadence requires.

---

1. Mint the replacement key

Follow Mint an API key to create a new key with the same scopes and cluster allow-list as the one being retired. Name it with a -vN suffix or the current date to distinguish it from the old key.

---

2. Deploy both keys side-by-side

Store the new key in your secrets store alongside the old one. The integration should still authenticate with the old key at this point — the new key is staged for activation.

---

3. Cut over to the new key

Update the integration's configuration to read the new key and redeploy. Watch for 401 UNAUTHORIZED responses during the cutover window — they signal a deploy that hasn't picked up the new key yet.

---

4. Revoke the old key

Once the integration is fully on the new key and no 401 traffic remains, go to Settings → API Keys in the dashboard and revoke the old key. Revocation takes effect on the next request, with no grace window.

A revoked key returns 401 UNAUTHORIZED immediately. If revoking causes new 401 traffic, an unknown caller is still using the old key — investigate the source before re-minting.

---

When to revoke immediately (skip the cutover)

Revoke without staging a replacement when:

• The key is exposed in logs, source control, screenshots, or any channel you don't fully control.
• The integration that owned the key is decommissioned.
• The person who created the key leaves the team and no other owner is on file.
• Unexplained 401 traffic appears on a key that should not be in use.

---

See also

• Mint an API key — the create flow.
• Authentication — the wire-level contract and 401/403 distinction.