2026-10-01 · 6 min read · Rahul Chitturi
- jwt
- security
- 401
A JWT can fail before signature verification because of the crit header. crit lists extension header names that the recipient must understand. If any listed name is unknown to the verifier, the JWS is invalid even when the signature bytes are correct.
That rejection looks like a generic 401 in an API gateway. Rotating the signing key does not teach the verifier a new header extension.
Decode the protected header first
crit has to sit in the protected header, the first segment of a compact JWS. It is an array of names. Those names must also appear as header parameters. An empty array is not allowed. Names defined by the JWS and JWA specs, such as alg or kid, must not be listed in crit.
Decode that segment as Base64url and format the JSON. Then list which crit entries your verifier documents as supported. The 401 belongs to the first name that is absent from that list.
- Confirm crit is in the protected header, not the payload.
- Confirm every listed name exists in the header.
- Reject producers that send crit with an empty list.
- Do not treat an ignored unknown header as a successful crit check.
Do not confuse crit with exp or alg
An expired exp fails time checks after the header is accepted. A bad signature fails cryptographic checks. A crit failure means the verifier refused the token's header contract. Libraries that skip unknown headers will accept a token that a strict verifier rejects, which is unsafe when the extension changes how the payload is interpreted.
If the producer did not need the extension, remove crit and the extra header. If the producer did need it, both sides must implement that header before production traffic uses it.
Reproduce with a header fixture
Build two synthetic tokens that share a payload: one without crit, and one with a single unsupported name. The first should pass header processing in a test verifier. The second should fail with a header error, not an exp error.
Use Flashman's JWT decoder to inspect the protected header, the JSON formatter for the header object, the Base64 tool for the first segment, and diff to compare a token your gateway accepted with the token it rejected.