Settings

A JWT’s header names the key that signed it in kid, and a verifier looks for the key with that kid in the issuer’s published key set, the JWKS. “Kid not found” means none matched. The usual causes are a key rotation (the token was signed with a key the set has dropped), a stale cached set (a new key the verifier has not fetched yet), a token from another issuer or environment, or a token with no kid against a set with several keys. Put the token’s kid beside the kids the set has, and the cause is usually plain.

How the lookup works

A JWT is three base64url parts joined by dots. The first decodes to the header, for example {"alg":"ES256","kid":"2026-10"}. The issuer publishes its public keys as a JWKS at the jwks_uri named in its OpenID configuration, usually under /.well-known/, each key with its own kid. The verifier fetches the set, often caches it, takes the key whose kid is the token’s, and checks the signature with it.

What it looks like

One ES256 token, signed with key 2026-10, checked by JWKS against four different sets:

The set hasWhat JWKS saysWhich cause
2026-10, 2026-11Signature verifies, key “2026-10”None: the old key is still published beside the new one
2026-11, 2026-12The token names kid “2026-10”, which is not in the key set, and the set has 2 keys to choose from: “2026-11”, “2026-12”Rotation: the key that signed it is gone
2026-11 onlyThe token names kid “2026-10”, which is not in the set; key “2026-11” was tried as the only one that could fit. The signature does not verify against this keyRotation, where a verifier that tries a lone key reports a bad signature instead
2026-11, 2026-12, token without a kidThe token has no kid, and the set has 2 keys to choose fromThe issuer signs without kid

The causes, and the fix for each

  • The key was rotated out too soon. The token is older than the set: its kid is a date or a number that comes before the ones published. Tokens signed with the old key are still in use until they expire, so the old key has to stay in the set at least that long after signing moves to the new one. Republish it, and next time keep both for longer than the longest token lifetime.
  • The verifier’s copy of the set is out of date. The opposite case: the token’s kid is newer than anything the verifier has. The issuer has started signing with a new key and the verifier is using a cached set. Many libraries refetch the set when they meet an unknown kid, rate-limited; one that does not needs restarting, or its cache time shortening.
  • The token came from somewhere else. A token from staging checked against production’s set, or from one tenant against another’s, names a key the set never had. Compare the token’s iss claim with the issuer whose set is configured.
  • The token has no kid. With one key in the set, many verifiers use it; with several, they cannot choose. If you sign the tokens, set the kid header when signing.

One fix to avoid: fetching the key from a jku or x5u address written in the token itself. Whoever made the token chose that address, so a verifier that follows it lets the token pick the key that checks it.

Checking a token without sending it anywhere

  1. Open the issuer’s jwks_uri in a browser tab and copy the JSON.
  2. Paste the token and the set into JWKS. It picks the key as a verifier does, and when none fits it names the token’s kid beside the ones the set has. When one fits it verifies the signature and checks exp, nbf, aud and iss.
  3. To read only the header and claims, with no key, use JOT.

A token is a credential for as long as it is valid, which is a reason to check it in a tool that keeps it in the tab rather than one that sends it to a server.

Questions people ask about a JWT kid missing from the key set

What does kid not found in JWKS mean?

The kid in the token’s header names a signing key that is not in the key set the verifier is checking against. The key was rotated out, the verifier’s copy of the set is stale, or the token came from another issuer.

How long should an old signing key stay in the JWKS after rotation?

At least as long as the longest-lived token signed with it, counted from the moment signing moves to the new key. Until then, valid tokens still name the old kid.

Where do I find an issuer’s JWKS?

At the jwks_uri in its OpenID configuration, which is served at /.well-known/openid-configuration under the issuer’s address. The set is often at /.well-known/jwks.json, but the configuration is the one to trust.

Does a JWT have to have a kid?

No, the standard makes it optional. But a verifier can only choose the key without one if the set holds a single key, so an issuer with more than one key should always set it.

Is it safe to paste a JWT into an online decoder?

A JWT is a credential until it expires: anybody holding it can use it. Check it in a tool that keeps it on your device, or check one that has already expired.

Related tools

More on this

All 8 guides under “Showing the work is yours”.

What your files give away

A one-page checklist of what a photo, a document or a PDF says about you, free now. Then one letter a month, with one new tip.

No spam, unsubscribe at any time, nothing is shared.