kid (Key ID) Claim
The kid (Key ID) is an optional JWT header parameter that identifies which key was used to sign the token. During key rotation, multiple keys may be active simultaneously — the verifier looks up the secret or public key matching the kid value. This enables zero-downtime rotation without invalidating all outstanding tokens at once. kid values should be opaque identifiers mapped server-side, never trusted as security inputs on their own. Implementations across Node.js, Python, Go, Ruby, and Java follow the same RFC standards, so concepts transfer directly between stacks. Security reviews should treat this as part of your full authentication threat model, not an isolated configuration detail.
Why It Matters
Without kid, rotating a JWT secret immediately invalidates every active token. With kid and a key store that holds both old and new secrets during a transition window, you can rotate safely. Production systems should plan rotation using kid before the first secret compromise forces an emergency outage. Getting this wrong often surfaces only after an incident, when forged or replayed tokens expose gaps in validation or secret handling. Platform teams should encode these rules in libraries, linting, and deployment checklists so individual services cannot drift silently. Pair technical controls with monitoring: log verification failures, track unusual token lifetimes, and alert on spikes in 401 responses.
Code Example
{
"alg": "HS256",
"typ": "JWT",
"kid": "key-2024-07"
}Related Terms
Related Tools
Related Articles
Frequently Asked Questions
Is kid required?
No, but strongly recommended for any system that rotates signing keys or publishes multiple public keys via JWKS. Consult your JWT library documentation for exact option names, defaults, and error types. When in doubt, prefer stricter validation and shorter token lifetimes over permissive shortcuts.
Can kid be manipulated by attackers?
Yes — always validate kid against an allowlist of known key IDs, never trust arbitrary values from the token header. Consult your JWT library documentation for exact option names, defaults, and error types. When in doubt, prefer stricter validation and shorter token lifetimes over permissive shortcuts.
Where does kid appear?
In the JWT header, not the payload. Verifiers read kid before selecting the verification key. Consult your JWT library documentation for exact option names, defaults, and error types. When in doubt, prefer stricter validation and shorter token lifetimes over permissive shortcuts.