JWT signing keys
The key pairs an environment signs with, the three states they move through, and how to rotate one without breaking a live token.
Each environment holds its own signing keys, in the Console under Authentication → Signing keys. They sign both the access tokens your users carry and the id tokens the OAuth server issues — one set, one JWKS, because a verifier trusts an issuer and expects one place to fetch from.
The three states
Each key is in one of three states:
In usesignsThe key new tokens are signed with. Exactly one per environment.
StandbyverifiesPublished and able to verify, waiting to take over. Nothing is signed with it yet.
Previously usedverifiesPublished and able to verify, no longer signing.
RevokedrejectedOut of the JWKS and no longer accepted. Kept, so you can bring it back.
Every key except a revoked one is published in the JWKS. That is the point of the third state: a token signed moments before a handover has to keep working until it expires, and dropping its key early would reject requests that are perfectly valid.
Algorithms
ES256defaultECDSA on P-256. Small keys, short signatures, and the one to pick unless something forces otherwise.
RS256RSA, 2048 bits minimum. Reach for it when a client library or an older integration only speaks RSA.
EdDSAEd25519. The fastest to verify; check your library supports it first, as support is less universal than the other two.
The identifiers are the registered ones — ES256 and RS256 from
RFC 7518, EdDSA from
RFC 8037 — so a library that reads the
alg header knows what to do without configuration from you.
Rotating a key
Rotation is deliberately four steps, not one, because the slow part is out of our hands: clients cache the JWKS, and a key cannot start signing until they have seen it.
Add a key. It arrives in standby — published, verifying, signing nothing. Generate one, or import a private key you already hold in JWK format.
Wait. Long enough for clients to refetch the JWKS. How long is your call, and it depends on the cache lifetime of whatever verifies your tokens.
Promote it. New tokens are signed with the new key from that moment. The key that was in use drops to previously-used in the same write, so nothing it signed breaks.
Wait again, this time for the tokens. A token signed by the old key stays valid until its own expiry — nothing invalidates it early — so the wait is one access token lifetime.
Then revoke the old key. Nothing revokes it for you: revoking is the only way to stop its tokens being accepted, and doing it sooner rejects tokens that are still perfectly valid.
The key in use cannot be revoked. Promote another one first — the environment is never left with nothing to sign with.
Walking a rotation back
Revoking is reversible. A revoked or previously-used key can be restored, which puts it back to standby — published and verifying again — and from there you can promote it, returning the environment to the key it was signing with before.
This is what makes a rotation safe to attempt. If something downstream turns out not to have picked up the new key, you go back rather than scramble forward.
Deleting a key
A revoked key can be deleted, which removes it and its private half for good. There is no restoring it afterwards, so it is worth leaving a key revoked long enough to be sure nothing still needs it. Only a revoked key can be deleted — there is no path straight from signing to gone.
Promoting, revoking and deleting a key all require an elevated session. You will be asked to confirm who you are before the change goes through, the same as for any other sensitive action.
Importing your own key
If you already hold a key pair — because another provider issued it, or your infrastructure generates them — paste the private key as a JWK when adding one. It is stored encrypted and never leaves; only the public half is ever served.
The key has to carry its private component, RSA keys must be at least 2048 bits, and Edwards keys must use Ed25519. Anything else is refused rather than stored half-working.