JWKS and Key Rotation

The public key directory

A JWKS is a JSON document that lists an issuer's public signing keys, each tagged with a key identifier and the algorithm it is used with. Verifiers fetch this set from a well-known endpoint and use it to check the signatures on the tokens they receive. Because the keys involved are public keys, the document can be served openly to anyone, with no authentication required.

This published directory is precisely what lets independent services validate Merion-issued tokens locally, with no shared secret passing between them. The issuer alone holds the corresponding private keys and uses them to sign tokens; everyone else uses the matching public keys merely to verify. That asymmetry is what makes the whole arrangement safe to expose, and it is the foundation that makes painless key rotation possible.

Matching the key

Each JWT header carries a key identifier that names which key was used to sign that particular token. To verify a token, a service reads that identifier from the header and selects the matching key from the JWKS document it has fetched. This small piece of indirection is the mechanism that makes rotation work at all: the token itself effectively points at the key needed to check it.

If a service cannot find a key matching the identifier in its current copy of the JWKS, the correct behaviour is to refresh that copy once before giving up, in case a brand-new key has just been published that the service has not seen yet. Only after a refresh still fails to produce a match should the token be rejected. Designing for this case is what keeps verification working smoothly across a rotation.

Why rotate keys

Key rotation exists to limit the damage if a signing key is ever compromised, and more generally as a matter of good operational hygiene, much like changing passwords. Issuers periodically introduce a new signing key, begin signing freshly issued tokens with it, and later retire the old key once any tokens it signed have safely expired.

During the overlap period, both the old and new keys appear together in the published JWKS, so tokens signed by either remain verifiable for as long as they are valid. This staged approach is the entire reason rotation can happen without downtime for well-behaved clients: nothing is ever pulled out from under a token that is still in use. A client that refreshes its key set on demand will simply pick up the new key and carry on uninterrupted.

Caching responsibly

Fetching the JWKS on every incoming request would be needlessly wasteful, generating constant traffic to the issuer for data that rarely changes, so verifiers cache the key set instead. The art is in caching it with a sensible lifetime while also refreshing on demand whenever an unknown key identifier appears in a token. That combination gives you the performance of a cache without the risk of missing a freshly rotated key.

A cache that never refreshes will eventually reject perfectly valid tokens after a rotation; a cache that refreshes too eagerly defeats its own purpose. Most OIDC libraries strike this balance for you automatically, so you rarely implement it by hand. To see how the fetched keys are then actually used, revisit Validating a JWT or browse the Merion API documentation.