What is the kid header in a JWT?

Dark navy cover card with the title 'What is the kid header in a JWT?' in white and a green accent bar

The JWT kid header is the key ID: an optional field in the token header that tells the verifier which key signed the token. The verifier uses the kid to pick the matching public key from the issuer's JWK Set, which is what makes key rotation possible without breaking existing tokens. The kid only says which key to try; the signature check still decides whether the token is valid.

What the JWT kid header means in the standard

The kid header is defined in RFC 7515, section 4.1.4, as "a hint indicating which key was used to secure the JWS." The same section says the value is a case-sensitive string, its structure is unspecified, and using it is optional.

The RFC also gives the reason it exists: kid lets the signer explicitly signal a change of key to whoever verifies the token. When the token is used with a JSON Web Key, the kid value is matched against that key's own kid parameter.

A decoded header with a kid looks like this:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "rot-b"
}

The header is the first of the three parts of a JWT, so Base64URL-decoding that part shows the kid. No key needed.

How a verifier uses the kid to find the key

The verifier matches the token's kid against the kid of each key in a JWK Set and uses the one that matches. RFC 7517, section 4.5, names this use: choosing among a set of keys within a JWK Set during key rollover.

A cut-down JWK Set with two RSA keys (long n values shortened):

{
  "keys": [
    { "kty": "RSA", "kid": "rot-a", "use": "sig", "n": "…", "e": "AQAB" },
    { "kty": "RSA", "kid": "rot-b", "use": "sig", "n": "…", "e": "AQAB" }
  ]
}

For the token header above, the lookup runs:

  1. Decode the header and read "kid": "rot-b".
  2. Load the issuer's JWK Set (from a cache or its URL).
  3. Find the key whose kid is exactly rot-b. Case matters: Rot-B is a different key ID.
  4. Check that the key fits the expected algorithm, then verify the signature with it.
  5. If no key matches, refresh the set once (see below) and reject the token if there is still no match.

RFC 7517 says different keys in one JWK Set SHOULD have distinct kid values. Its one exception is keys of different types (kty) that the application treats as equivalent alternatives.

Where the JWK Set comes from

For OpenID Connect providers, the JWK Set lives at the URL in the jwks_uri field of the discovery document. OpenID Connect Discovery marks that field REQUIRED and says the URL MUST use https and holds the signing keys used to validate the provider's signatures.

Hard-code or configure that URL on the verifier side. Don't take it from the token.

Key rotation: why the kid matters most

The kid is what lets an issuer switch to a new signing key while old tokens are still in circulation. OpenID Connect Core, section 10.1.1, describes the flow:

  • The signer publishes its keys in a JWK Set at its jwks_uri and puts the signing key's kid in each token header.
  • To rotate, it adds the new key to the set, then starts signing with it whenever it chooses.
  • A verifier that sees an unfamiliar kid goes back to jwks_uri and fetches the set again.
  • The set SHOULD keep recently retired keys for a reasonable period, so tokens signed just before the switch still verify.

In the example, rot-a might be last month's key and rot-b the current one. Tokens signed with either verify until the issuer drops rot-a.

OpenID Connect Core makes the kid mandatory in one case: if the referenced JWK Set holds multiple keys, a kid value MUST be provided in the header. Hence the "missing kid" errors from many verification libraries. They hold several keys and can't choose.

How to choose a kid value

Any unique, case-sensitive string works, because the standard leaves the format open. Teams use dates, counters or random IDs.

RFC 7638 offers a standard one. It defines a JWK Thumbprint, a hash over a canonical form of the key, and names the base64url-encoded thumbprint as one way to fill the kid. Anyone holding the public key can recompute the ID and confirm it belongs to that key.

My take: use the thumbprint. A readable label like prod-2026 looks nice in logs, but it says nothing about the key, and two teams can pick the same label.

Security: treat the kid as untrusted input

The kid comes from the token, and the verifier reads it before it has checked the signature, so an attacker controls it. RFC 8725, the JWT best-practices document, says in section 3.10 that applications use the kid for key lookup and should make sure it doesn't create SQL or LDAP injection holes, by validating or sanitizing the value.

The same section warns about two related headers. Blindly following a jku (JWK Set URL) or x5u header, which can hold any URL, could lead to server-side request forgery. In practice:

  • Look the kid up only in a key set you loaded from a URL you configured.
  • Never build a file path, SQL query or URL from the raw kid.
  • Ignore jku and x5u values in incoming tokens unless they match an allow list.

The kid never decides the algorithm, either. Pin the algorithms you accept (see the alg none attack post). A matching kid proves nothing until the signature checks out, which is the gap between decoding vs verifying a JWT.

How to see the kid in a token

Decode the header part of the token and look for the kid field. Our JWT decoder shows the header, payload and signature, so you can read the kid along with alg and the expiry times.

The limitation: the decoder only decodes. It does not verify the signature, so it shows you a kid but can't tell you whether the matching key signed the token. For that, run the lookup above in your verification library against the issuer's JWK Set. If the token is sensitive, read how to decode a JWT safely first.

FAQ

Is the kid header required in a JWT?

Not by the JWS standard, which marks it optional. OpenID Connect does require it when the signer's JWK Set holds more than one key, and many libraries refuse to verify a token without one when they look keys up in a JWK Set.

What format does a kid value use?

Any case-sensitive string. The standard leaves its structure unspecified. A common, standard choice is the base64url-encoded JWK Thumbprint of the key, defined in RFC 7638.

Is the kid header part of the signature?

Yes. The header is part of the signed input in a JWS, so changing the kid breaks the signature. But the verifier reads the kid before it has checked anything, so the value must still be treated as untrusted input.

Where do I find the key that matches a kid?

In the issuer's JWK Set. For OpenID Connect providers, the discovery document's jwks_uri field gives the HTTPS URL of that set. Pick the key whose kid equals the token header's kid.

What happens when the kid is not in the JWK Set?

Under OpenID Connect's rotation rules, the verifier fetches the JWK Set from jwks_uri again, because an unfamiliar kid usually means the issuer started using a new key. If it is still missing, reject the token.

Sources