What is a JWT, and how do you read one?

The three parts

A JWT is three pieces joined by dots:

• The header says what kind of token it is and how it was signed, for example the algorithm HS256.
• The payload holds the claims, the facts the token states about a user or session.
• The signature proves the token has not been changed, and can only be checked with the right key.

header.payload.signature

Why it looks like gibberish but is not

The header and payload are JSON written in Base64URL, a way of turning text into letters, digits, dashes and underscores. It is an encoding, not encryption. Anyone can decode it. Paste a token into the JWT decoder and the JSON appears.

Common claims

The three time claims are Unix timestamps in seconds. The decoder turns them into readable dates and tells you whether the token has expired.

• sub: the subject, usually the user ID.
• iss: the issuer, who created the token.
• aud: the audience, who it is meant for.
• iat: when it was issued.
• nbf: the time before which it is not valid.
• exp: when it expires.

Decoding is not verifying

A decoder shows what a token says. It cannot tell you whether the token is genuine, because that needs the secret or public key. A forged token decodes just as cleanly as a real one.

Your server must always verify the signature, and check the expiry and the audience, before it trusts any claim.

What not to put in a token

Because anyone holding the token can read the payload, never put passwords, secrets or private personal data in it. Keep payloads small and treat the token like a password: whoever has it can usually act as that user until it expires.

Debugging tips

• A "token expired" error often means the server clock and the issuing clock disagree. Compare the exp time with the current time.
• If decoding fails, check that you copied the whole token and that it has exactly two dots.
• Avoid pasting live production tokens into websites. Use a test token when you can.