Encoding & Transport

How to choose the right JWKS key by kid and what to do when it is missing

Learn how to match a JWT to the correct key in a JWKS document and how to handle tokens that arrive without a usable kid.

Encrypt Online Editorial TeamPublished April 15, 20263 min read

Encrypt Online guide cover on a sky blue background with the headline "Choose a JWKS key". JWK sits above two staggered metadata strokes, one with a leading field dot.

A JWKS with five keys is normal. A verifier that tries all five blindly is where debugging gets messy. The clean workflow is to inspect the header, select the intended key, and then verify with that one candidate.

When kid is missing, narrow the candidates by algorithm, key use, and issuer before attempting verification.

In brief

What it is: The kid header identifies which key in a published key set should be used to verify a token.

Why it matters: A key set exists so providers can rotate keys. Picking the wrong entry wastes time and can create misleading verification failures.

Worth knowing: When kid is missing, first constrain candidates by issuer, algorithm, key type, use, and policy.

Match the token header to the key set

Open the JWT header first. Read alg, kid, and anything else that narrows the verification path. If the header says RS256, skip EC and OKP keys immediately. If it includes kid, use it as a selector inside the JWKS. That one step keeps a routine verification job from turning into trial-and-error.

This is also where you catch naming issues. Some teams cache an old JWKS, or they pin a key from a previous rotation. A kid mismatch often means your cache is stale, your environment points at the wrong issuer, or you are looking at the wrong tenant entirely.

What to do when kid is missing

A missing kid is not ideal, but it is not automatically fatal. First, reduce the search space. Filter the JWKS by algorithm family, by intended use such as sig, and by issuer context. If only one public key plausibly matches, use that path. If multiple keys remain, stop guessing and go back to the identity provider documentation or issuer configuration.

When a rotating provider omits kid, use a documented JWKS endpoint for each issuer or a pinned thumbprint list to narrow the candidates.

Filter by alg family first.
Prefer keys where use is sig or key_ops includes verify.
Treat multiple plausible matches as a configuration problem, not a parser bug.

Caching and rotation mistakes that look like crypto bugs

A large share of “signature invalid” incidents are stale-key incidents. The token is fine. Your verifier is reading yesterday’s JWKS, or a deployment image was built with a pinned PEM file and never refreshed. Rotation turns this into an intermittent bug, which is why it feels harder than it is.

The fix is procedural. Record which issuer you used, which kid you expected, and which key set version you actually loaded. Once that trail is visible, the failure usually stops looking mysterious.

See it in a small example

Notice: Treat a matching kid as a pointer to a JWKS record and confirm the key separately.

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "login-prod-2026-02"
}

What to verify

Decode the header and write down iss, alg, and kid.
Confirm the JWKS endpoint belongs to the same issuer or tenant.
If kid is missing and more than one key still fits, stop and resolve the configuration source.