How to Read a JWT: Header, Payload and Signature

A JSON Web Token, or JWT, is a compact string that carries a few facts, such as who a user is and when a login expires. You see them in API calls and login systems. This guide explains the three parts, the standard claims, the difference between reading a token and trusting it, and the common mistakes.

The three parts

A JWT is three pieces of base64url text joined by dots: header.payload.signature. The header is a small JSON object that says how the token is signed, for example the algorithm HS256 and the type JWT. The payload is a JSON object of claims, the facts the token carries. The signature is a value computed from the first two parts with a secret or a private key, which lets the receiver check that nobody changed them. The format is defined in RFC 7519.

Because the parts are only base64url encoded, anyone who holds the token can read the header and payload. Nothing is hidden. This is the same as with plain Base64: encoding is not encryption. A token in the five-part form, known as a JWE, is encrypted, and cannot be read without the key. The decoder on this site says so when it meets one.

The standard claims

• iss: the issuer, who created the token.
• sub: the subject, usually the user the token is about.
• aud: the audience, who the token is meant for. A recipient that is not listed must reject it.
• exp: the expiry time. The token must not be accepted at or after it.
• nbf: not before. The token must not be accepted earlier.
• iat: when the token was issued.
• jti: a unique ID, which can help detect replays.

The three time claims are numbers of seconds since 1 January 1970 UTC, the same as a Unix timestamp. A payload that says exp 1700000000 expires on 14 November 2023 at 22:13:20 UTC. Fractions are allowed. A common mistake is to treat these as milliseconds, which puts the date thousands of years ahead.

Decoding is not verifying

Reading a token tells you what it claims, not whether the claims are true. Anyone can write a payload that says admin. Only a check of the signature, with the right key, shows that the token was made by the issuer and has not been altered. RFC 7519 says that if any of the validation steps fail, the token must be rejected. That is a job for the server, using a well-tested library. A web page that decodes a token, including the tool here, cannot prove it is genuine.

Mistakes that make tokens unsafe

• Accepting the none algorithm. A token whose header says alg none is unsigned. RFC 8725 warns that libraries should not accept it unless the caller explicitly asks.
• Letting the token choose the algorithm. The application should decide which algorithms it accepts, and tie each key to one algorithm.
• Skipping the audience and issuer checks. A valid token for one service should not work on another.
• Putting secrets in the payload, because everyone can read it.
• Using a short, guessable password as the signing key for HS256. The key should be random and long.
• Trusting header fields such as kid or jku without validating them, since they can be used for injection or to make the server fetch a URL.
• Ignoring expiry, or setting it so long that a stolen token stays useful.

Is it safe to paste a token into an online decoder?

A token is a credential. Anyone who has a live token can usually use it until it expires. Pasting one into a website that sends it to a server would be a risk. The decoder on this site works entirely in your browser and sends nothing, but as a habit, avoid pasting production tokens into tools you cannot inspect, and prefer to use a short-lived token from a test environment.

Reading a token step by step

To read a token by hand, split it at the dots. Decode the first two parts from Base64URL, which is Base64 with a hyphen and an underscore in place of the plus and the slash, and no equals padding. The result is two JSON objects. Look at alg in the header, then at exp, nbf and iat in the payload, and compare the times with the current time in UTC. If the token is outside its time window, it is not valid, whatever the signature says.

Sources

• RFC 7519: JSON Web Token (JWT)
• RFC 8725: JSON Web Token Best Current Practices
• JSON Web Token (Wikipedia)