Rotation is three steps in a fixed order. Creating a key never revokes another one, so the overlap between the old credential and the new one is entirely under your control — and getting the order wrong is the difference between a rotation and an outage. This is a human action. apikeys:manage is not grantable to an API key, so it needs a browser session (or a session-authenticated curl, as below). A leaked credential that could mint another would turn a bounded, expiring key into permanent access, and revoking the original would achieve nothing.

​
1. Create the replacement

Grant it exactly the scopes the old one held — no more, and a caller may not grant a scope they do not themselves hold.
expires_at is optional and defaults to 90 days from now; the maximum is 365. The secret is in this response and nowhere else, ever. There is no endpoint that reads it back — if you lose it, revoke this key and issue another. To check what the old key held first:
That listing includes revoked and expired keys. A list that hid them could not answer “what has this organisation ever issued”, which is the first question after a leak and the whole basis of an offboarding review.

​
2. Deploy it

Update the secret in every place the old one is configured, and let the pipelines run at least once on the new credential. last_used_at on the new key is the evidence that they did:
Both keys are valid during this window. That is the point of doing it in this order.

​
3. Revoke the old one

Revocation is immediate — the next request with that credential is 401 — and idempotent, so a retried revocation during an incident does not fail. The row is never deleted: “which credential did this, and when did we stop trusting it” is exactly what an incident review needs.

​
Expiry is mandatory

There is no value meaning “never”. Default 90 days, maximum 365. A credential with no expiry is one nobody will rotate, and the ceiling is what makes this procedure a routine rather than an emergency. Set a reminder before the expiry date. An expired key fails exactly like a revoked one, and the 401 is deliberately identical for missing, malformed, unknown, wrong-secret, revoked and expired — distinguishing them would tell an attacker which part of a forged credential to fix next.

​
If a key has leaked

Reverse the order: revoke first, then create and deploy. A short outage is the correct trade against a live credential in a public repository. The prefix is the public half and is safe to log, which is what lets you identify which credential leaked from a log line or a paste.

​
Gotchas

  • Maximum 50 active keys per tenant. Rotation is fine within that; a script that creates and never revokes will hit it.
  • Never a self-service pipeline action. A CI job cannot rotate its own credential, by design.
  • Rotating a webhook signing secret is a different procedure and does overlap automatically — see Verify a webhook signature.
  • Scope reduction is a good moment. Rotation is the cheapest time to notice that a key holds findings:suppress it never uses.

​
See also

  • Authentication — credential format and lifecycle.
  • Scopes — what may be granted, and what may never be.