What is a JWT and how do you read one?
A JWT (JSON Web Token) is a small piece of text most often used to prove that a user has signed in. It has three parts separated by dots, and reading it is easier than it looks.
Three parts: header, payload, signature
A JWT looks like this: xxxxx.yyyyy.zzzzz. Each of the three parts separated by dots is encoded with Base64url.
- Header: says which signing algorithm is used, for example HS256.
- Payload: the actual data. Fields (claims) such as who the user is (sub), who issued the token (iss), when it was issued (iat) and when it expires (exp) live here.
- Signature: the header and payload signed with a secret key. If the token is changed the signature no longer matches.
A JWT is not encrypted
This is the most common misunderstanding. A standard JWT is signed but not encrypted. The payload is only encoded, so anyone who decodes Base64url can read it. Never put passwords, card numbers or other secrets in a JWT.
The signature only guarantees that the token has not been changed since it was issued. It does not hide the contents.
Reading is not the same as verifying
Tools like the JWT decoder only read the payload. Verifying the signature needs the secret (or public) key and should be done by the server that accepts the token. Seeing the contents of a token does not prove it is genuine, since anyone can craft a JWT with fake contents.
Time fields: exp, iat, nbf
These fields hold the number of seconds since 1 January 1970 (Unix time). exp is the expiry time, iat is when it was issued and nbf means "not valid before". To check whether a token is still valid, see whether exp is after the current time. The timestamp tool turns the numbers into readable dates.
Common security mistakes
- Trusting the payload without verifying the signature.
- Blindly trusting the "alg" field on the server. Pin the accepted algorithm.
- Issuing very long-lived tokens. Short-lived tokens with a refresh mechanism are safer.
- Storing the token in localStorage. If a malicious script gets into the page it can read the token, which is why serious applications often prefer HttpOnly cookies.
Do not share valid tokens from live systems with others or on public sites. Our tool decodes the token in your browser and never sends it to a server.