JWT decoder: what is inside a token, and what is not

The three parts

• Header — the signing algorithm (`alg`) and token type (`typ`), for example HS256.
• Payload — the claims: who the token is about, when it was issued and when it expires.
• Signature — computed over the first two segments with the issuer’s key, which is why a decoder shows it but cannot check it.

                eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9 . eyJzdWIiOiIxMjMiLCJleHAiOjE3NjAwMDAwMDB9 . signature
           header                            payload                       signature
              

The claims that explain most failures

• `exp` (expiry) — the single most common cause of a 401. A token that expired two minutes ago is rejected before anything else is examined.
• `nbf` (not before) — the mirror image: a token used before its validity window is rejected.
• `iat` (issued at) — useful for working out how old a session is, and for spotting clocks that disagree.
• `aud` (audience) and `iss` (issuer) — mismatches here mean the token is valid but was issued for a different service, which fails in confusing ways.

Time claims are UTC seconds since the Unix epoch. If a token looks valid but expires far too early or late, check for a clock problem or a payload carrying milliseconds where seconds were expected.

Why you should never trust `alg` blindly

Two attacks are old enough to be famous and still appear in the wild. The `none` algorithm tells the verifier there is no signature at all; a server that reads the header instead of enforcing its own expected algorithm accepts it. And in RSA/HS confusion, an attacker signs with the public key as an HMAC secret, tricking a server that accepts both families. The defence in both cases lives in the verifier, not the decoder: pin the expected algorithm server-side and never derive it from the token itself.

Decode locally, always

A JWT is a credential: whoever holds it can act as the user until it expires. Pasting a real one into a website that posts it to a server hands over a live session for zero benefit, since decoding is base64url arithmetic that any browser can do in microseconds. The YamlBox JWT decoder parses the token in the page, shows the timestamp claims as readable UTC dates, and keeps working with the network disabled — the only kind of decoder worth using on a production token.

A debugging routine that works

1. Decode and read `exp` first — half of all “invalid token” reports end here.
2. Check `aud` and `iss` against what the API expects, then `nbf` for clock skew.
3. Compare the decoded claims with what your code assumes about roles or scopes.
4. If the claims look right and it still fails, the problem is verification — wrong key, rotated secret, or an algorithm mismatch.