Developer tools · JWT decoder
The JWT Header Explained: alg, typ, kid and the Fields to Distrust
· How it works
jwt security authentication
The header tells a verifier how the token was signed and which key to use. This post explains each common header field, what a verifier may rely on, and which fields must never be trusted from the token itself.
The small JSON object nobody reads — and the verification decisions it influences
The header is small enough to overlook, yet its fields often participate in verification routing. That makes it dangerous to confuse visibility with authority. ToolAcre decodes the header as a JSON object and shows its properties, but every byte came from the token holder and remains untrusted input.
A verifier may use a header value only inside constraints established from trusted configuration. It should not let the token invent an accepted algorithm, issuer or remote key source. The decoder’s job ends at readable JSON plus warnings; it never chooses a key or produces an allow or deny decision.
alg display: the decoder explains only the algorithms named in its implementation
`alg` declares the algorithm the token claims was used. ToolAcre has explanatory notes for HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384 and PS512, plus a warning for `none`. Any other string is displayed as unrecognised rather than treated as supported.
This list is a display feature, not a catalogue of algorithms that ToolAcre can verify: it verifies none of them. A backend must pin its permitted choices independently and reject a mismatch. Reading `alg: RS256` cannot prove RSA was used, just as reading `alg: none` cannot safely authorize an unsigned token.
typ and cty — declaring the token type, the at+jwt profile for access tokens, and nested JWTs
`typ` describes the media type or profile the producer intends. ToolAcre warns when a string value differs from `JWT`; it does not enforce profile semantics. A `cty` field can describe nested content, but the current decoder has no nested-token processing path and does not interpret that field.
Explicit typing can help a verifier keep different token classes separate when its policy defines expected values. The check still belongs to that verifier. A token cannot make itself an access token merely by announcing a preferred label, and a decode panel cannot determine which application endpoint should consume it.
kid — the key identifier that lets verifiers rotate keys without downtime
`kid` is a key identifier, not key material and not proof of ownership. A service that rotates several trusted keys can use an authenticated issuer context and a constrained identifier to locate a candidate. The identifier must remain input to a controlled lookup rather than a file path, query fragment or arbitrary URL.
ToolAcre leaves `kid` visible in the header JSON but does not resolve it. That restraint matters: no trusted key store is available to a public decoding page. If a 401 follows rotation, compare the displayed identifier with server-side key inventory and logs without assuming the token’s suggested key is legitimate.
jku, x5u, jwk and x5c — header fields that point at keys, and why a verifier must never fetch or trust them blindly
Fields such as `jku` and `x5u` can name locations, while `jwk` and `x5c` can carry key-related data. Their presence does not make those locations or values trusted. Fetching a URL or accepting embedded material solely because an unverified header supplied it hands a security decision to the requester.
A safe verifier obtains keys through an issuer relationship and network policy established outside the token. ToolAcre neither fetches header URLs nor builds trust from embedded keys. During review, seeing one of these fields is a prompt to inspect verifier configuration, not an instruction to follow the header.
crit — extensions a verifier must understand or reject
`crit` signals that particular extensions require understanding by the recipient. A verifier that supports such an extension needs an explicit implementation and rejection path for unknown critical names. Ignoring an unfamiliar critical marker can make producer and consumer interpret the protected content differently.
The decode-only implementation does not process `crit`, so it can show the raw array without claiming compatibility. This is another boundary between inspection and validation. If a production token relies on critical extensions, verify behavior in the actual library and configuration rather than inferring support from readable JSON.
Worked example — reading a realistic header and deciding which fields inform verification and which are merely informational
Consider `{"alg":"RS256","typ":"JWT","kid":"rotate-7"}`. ToolAcre pretty-prints all three fields and explains that RS256 verification needs an issuer public key. A reviewer can note the declared algorithm and key identifier, then compare them with the server’s pinned policy and trusted key set.
The fields inform investigation but decide nothing independently. If the server permits only another algorithm, cannot find `rotate-7` in the correct issuer set or rejects the signature, the readable header does not override that result. Equally, changing the header text without recomputing a valid signature must not be accepted.
Takeaway: the header is input, not authority — the ToolAcre JWT decoder shows the header so you can read it; the verifier must decide independently what to trust
Treat the JWT header as input, not authority. Its values can help select among choices already authorized by configuration, identify a likely rotation problem or explain a profile mismatch. They cannot establish trust in their own algorithm, key, URL or token type.
Use ToolAcre to read a test header and surface suspicious values such as missing `alg`, `none` or an unexpected `typ`. Then move to the configured verifier for every consequential decision. Decoding does not prove authenticity, integrity, authorization or issuer identity, regardless of how plausible the header looks.