crit (Critical) Header Parameter in a JWT
crit lists header parameter names that the recipient must understand and process. Anything named there that a verifier does not implement forces it to reject the token rather than ignore the parameter.
At a glance
- Parameter
- crit (Critical)
- Defined in
- RFC 7515 section 4.1.11
- Value type
- Array of strings, each an extension header parameter name
- May not contain
- Names registered by RFC 7515 or RFC 7518, duplicates, or an empty list. Any of those makes the token invalid.
- Behaviour
- Fails closed: an unrecognized critical name means reject, never ignore
- In the decoder
- Shown in the header JSON as an array. The tool decodes and verifies signatures; it does not implement JOSE extensions.
In detail
Unknown header parameters are normally ignored, which is what lets JOSE evolve. crit is the escape hatch for the cases where ignoring one would be unsafe: it names extensions that change how the token must be understood, so a verifier that does not implement them has to refuse rather than proceed on a partial reading. The design decision is to fail closed, and it is the right one.
The rules on the contents are strict and worth reading once. The list must not be empty, must not contain duplicates, and must not name any parameter that RFC 7515 or RFC 7518 already defines, since those are ones every implementation is expected to handle anyway. Each name in the list must also actually appear in the same header. Breaking any of these makes the token invalid, not merely unusual.
The best known extension it guards is b64 from RFC 7797, which switches off base64url encoding of the payload for detached signatures over large or binary content. Because a verifier that missed b64 would compute the signature over the wrong bytes and could reach a wrong conclusion, RFC 7797 requires b64 to be listed in crit whenever it is used.
In practice crit is rare, and its presence in a token is a signal that something non standard is going on and that a general purpose verifier may not be the right one. The decoder shows the array in the header JSON alongside whatever extension parameters accompany it. It decodes tokens and verifies signatures with the algorithms in its table, and does not implement JOSE extensions, so a critical extension is something to notice here rather than something the tool acts on.
Examples
{
"alg": "HS256",
"b64": false,
"crit": ["b64"]
}b64 set to false means the payload is not base64url encoded. Listing it in crit forces any verifier that does not implement RFC 7797 to reject the token.
{ "alg": "HS256", "crit": [] } // empty list, invalid
{ "alg": "HS256", "crit": ["alg"] } // names a registered parameter, invalid
{ "alg": "HS256", "crit": ["b64"] } // b64 is not present in the header, invalidThings that catch people out
- Ignoring an unrecognized name in crit. The parameter exists precisely to make that case a rejection.
- Listing a registered parameter such as alg or kid. RFC 7515 forbids it and a conforming verifier rejects the token.
- Naming an extension in crit without including the parameter itself in the same header. That is invalid too.
Try it: JWT Decoder
Paste a token to decode the header and payload, read the claims and expiry, and verify the signature in your browser. Nothing is uploaded.
JWT Decoder
LOCAL · Browser-OnlyDecode and inspect JSON Web Tokens without sending them to a server
Related JWT claims and algorithms
All jwt claims and algorithms →alg (Algorithm) Header Parameter in a JWT
The alg header names the algorithm used to sign a JWT. Why the accepted algorithms belong in configuration, and what the decoder does with the value.
typ (Type) Header Parameter in a JWT
The typ header declares the media type of a token. Why at+jwt exists, how typ prevents cross token confusion, and what the decoder flags.
cty (Content Type) Header Parameter in a JWT
The cty header describes the payload rather than the token. How the value JWT signals a nested token, and when nesting is actually worth it.
iss (Issuer) Claim in a JWT
The iss claim names who issued a token. What goes in it, why validators compare it byte for byte, and how the decoder displays it.
sub (Subject) Claim in a JWT
The sub claim says who the token is about. Why it is only unique within one issuer, what pairwise subjects change, and how the decoder shows it.
aud (Audience) Claim in a JWT
The aud claim names who a token is for. Why every API must check it, how the string and array forms differ, and what the decoder shows.
Tools for this
- JWT Decoder Free online JWT decoder - decode and inspect JSON Web Tokens without sending them to a server