How a JWT is built
A JWT is three Base64url-encoded parts joined by dots:
header.payload.signature- Header: which algorithm signed it (
alg) and the token type (typ). - Payload: the claims, which are facts about the user and the token, such as
sub,expandroles. - Signature:
HMACSHA256(base64url(header) + "." + base64url(payload), secret)for HS256. Change one character of the payload and the signature no longer matches.
Registered claims cheat sheet
| Claim | Name | What it’s for |
|---|---|---|
iss | Issuer | Who created the token |
sub | Subject | Who it’s about, usually a user ID |
aud | Audience | Which service should accept it |
exp | Expiration | Reject after this Unix time |
nbf | Not before | Reject before this Unix time |
iat | Issued at | When it was created |
jti | JWT ID | Unique ID, useful for revocation |
Debugging a token that won’t work
Tokens get damaged on their way through logs, emails and config files. The decoder marks the damage on the token itself and shows everything it can still read:
- Line breaks and spaces from a wrapped log line are marked and removed in one click.
- Standard Base64 (
+ / =) instead of URL-safe is converted. - Missing or extra dots are pointed out, including a cut-off signature.
- A broken header or payload is laid out with the exact JSON error marked, just like the JSON formatter.
- Time claims: expired tokens,
nbfin the future, aniatin the future (a server clock running fast) andexpin milliseconds are all called out. - Secret mix-ups: if the signature only matches with the secret read as Base64 (or as plain text), the verifier says so.
Decoding a JWT in code
Decoding (no verification) is just Base64url and JSON:
const [, payload] = token.split('.');
const claims = JSON.parse(atob(payload.replace(/-/g, '+').replace(/_/g, '/')));To verify, use a proper library rather than rolling your own: jose (JavaScript), PyJWT (Python), golang-jwt (Go). Always pin the expected algorithm and check exp, aud and iss.
exp passed, does aud match your API, and is the server clock in sync? Clock skew of a minute or two is a classic cause.Questions people ask
Is it safe to paste a real token here?
Is a JWT encrypted?
Why can’t I verify RS256 or ES256 tokens?
/.well-known/jwks.json. This tool verifies shared-secret HMAC tokens (HS256, HS384, HS512).What does “exp” mean?
Why does my server reject this token?
exp in the past, an nbf in the future, or an exp written in milliseconds instead of seconds. All three are flagged in the claims table. If the claims look fine, check the signature. A common mix-up is a secret stored as Base64 but used as plain text, and the verifier tells you when that’s the case.