Token Signing Keys
What this screen is for
Token signing keys shows the keys that sign every user access token the platform issues, and lets a platform super administrator rotate them on demand or withdraw one after a suspected disclosure.
Every access token names the key that signed it, and every service that checks a token looks that key up in the set the platform publishes. That is why keys can change without signing anyone out: a key is published before it signs, and stays published after it stops signing until every token it signed has expired.
You do not have to do anything here for rotation to happen. The platform rotates on its own schedule and removes retired keys when their time comes; this screen shows you where that cycle stands.
What must exist first
- You work in the platform context. A request from a customer tenant is refused whatever permissions it carries.
- The permission to read the token signing keys, held by the built-in platform administrator, operator, auditor and viewer roles, fills the table.
- The permission to manage them turns on Rotate now and Revoke. Only the built-in platform super administrator holds it. Without it the screen says it is read-only.
- A bound key-protection backend. The keys are sealed by it; while it is not bound, the screen can neither read nor change them and tells you to bind it under HSM / Cloud KMS.
- The key set itself. The platform creates it within a minute of its first start; until then the screen says it has not been initialized yet.
Decisions you make here
Reading the table
Each row is one published key, with its state, its key ID (kid) and three instants the server computed:
- Next — published, not signing yet. It becomes the signing key at the next rotation.
- Active — the one key signing tokens now. Signing since is when it was promoted.
- Previous — no longer signing. Leaves the set is when it is removed, once every token it signed has expired.
The screen never computes a date itself. Rotation eligibility and removal times come from the server, and Refresh reads them again.
Rotating now
Rotate now promotes the Next key, turns the Active key into a Previous key, and publishes a fresh Next key, in one step. No signed-in user is logged out.
It is available only from the instant the screen states. A Next key must have been published for a few minutes first, so that every service already holds it before its first token arrives. Asking earlier is refused and nothing changes.
You rarely need it: the platform rotates by itself when the Active key reaches the age set in Access & Identity → JWT (90 days unless changed).
Revoking a key
Revoke withdraws one key from the set at once. It is for an incident, not for routine rotation, and it asks for a reason that is recorded in the signed audit event — at most 1,000 bytes. You then confirm in a second step.
What follows depends on the key:
- Active — the Next key starts signing immediately, even if some services have not cached it yet, and a new Next key is published. Tokens the revoked key signed stop being accepted.
- Next — it has signed nothing; a fresh Next key replaces it.
- Previous — tokens it signed stop being accepted.
A revoked key is removed, not demoted, and cannot be restored. Services stop accepting it within about ten minutes, as they refresh the published set.
When another change got there first
Only one change to the key set is committed at a time. If the platform's own schedule, or another administrator, changed the set between your reading and your action, your action is refused, nothing changes, and the screen reads the set again for you to check before retrying.
A revocation also checks the key's state. The confirmation shows what revoking the key does in the state it is in now, and your request names that state. If a rotation moved the key first — the Next key you meant to discard is now signing — the revocation is refused and nothing changes; the screen shows the key's current state and reads the set again. Nothing is sent again for you: decide again, and confirm if the revocation is still what you want.
How it relates to other screens
The age at which the platform rotates by itself is a setting on the identity screen:
The backend that seals these keys, and the rest of this group: