Decode a JWT

The three parts of a JWT

A JWT is three pieces of base64url text joined by dots: header.payload.signature. The first two are JSON that is encoded, not encrypted. That is why a decoder can read them without any key, and why tokens almost always start with eyJ, which is how {" begins in Base64.

• Header: how the token is signed. alg names the algorithm (HS256 for a shared secret, RS256 or ES256 for a key pair), typ is usually JWT, and kid tells the server which of its keys to check against.
• Payload: the claims. The registered ones are iss (who issued it), sub (who it is about), aud (who it is for), exp (when it expires), nbf (not valid before), iat (issued at) and jti (a unique ID). Providers add their own, such as scope, roles, email or a tenant ID.
• Signature: a MAC or digital signature over the first two parts. It proves the token came from someone holding the key and has not been changed since.

The times in exp, nbf and iat are Unix seconds, not milliseconds. Octoolo turns them into your local time; for any other timestamp in a payload, the Unix timestamp converter does the same.

Decoding is not verifying

Anyone can decode a JWT. Only someone with the right key can verify it. Octoolo decodes, and says so under every result: the signature is not checked, because that needs the issuer's key.

This cuts both ways. For debugging, decoding is all you need: you want to see what the token claims, not prove it. But code must never trust a decoded payload on its own. A server has to verify the signature with the algorithm and key it expects (a shared secret for HS256, the issuer's public key for RS256 and ES256, often fetched from its JWKS address), then check exp, nbf, iss and aud. Libraries that accepted alg "none", or let the token choose its own algorithm, have been a classic source of security holes.

Because anyone holding the token can read the payload, it is no place for secrets. If you find a password, an internal address or more personal data than needed in a token's claims, raise it with whoever issues the token.

Debugging a 401 with a decoded token

When an API turns a token away, the payload usually tells you why:

• Expired. The Dates show (expired) after exp. Access tokens often live for minutes rather than days, so one copied this morning may be dead by lunch. Get a fresh one.
• Not valid yet. An nbf in the future, often by only a few seconds, points to a clock that is out of step on the server or on your PC.
• Wrong audience. aud names a different API from the one you are calling, a common mix-up between ID tokens and access tokens from the same sign-in.
• Missing scope or role. The scope or roles claim lacks the permission the endpoint needs.
• Wrong issuer. iss points at staging while you are calling production, or the other way round.

If the result says "A JWT has three parts separated by dots", only part of the token was pasted, or something else entirely. "This token's parts are not Base64 JSON" usually means extra text around the token, or an encrypted JWE token, which has five parts and cannot be read without its key.

Why decode tokens offline

A bearer token is a key to an account until it expires. Whoever holds it can call the API as that user, with no password needed. Even so, pasting production tokens into web decoders is a routine part of debugging. Many of those pages decode in the browser and never send anything on; you are still pasting a live credential into a page whose scripts can change on any day, in a browser where extensions can read the page.

The Dev Toolbox decodes inside the Octoolo app, with no website and no server behind it, and it works offline. The token is gone from the tool as soon as you switch to another one. For the pieces around a token, Base64 reads a single base64url segment, and the JSON formatter tidies a payload you have copied out.