Reading a JSON Web Token
A JSON Web Token, or JWT, is three base64url strings joined by dots. Anyone holding a token can decode the first two parts and read them. Only a server with the right key can check the third part, and that check is the only thing that makes a token trustworthy.
Decode a JWT (no verification)
The sample token above is a demo we built for this page. It was signed with HS256 and the throwaway key example-secret-not-for-real-use, and it expired long ago. Do not paste a live production token into any website, including this one; decode real tokens in your own terminal.
The three parts
header . payload . signature
- Header – JSON that names the signing algorithm. The sample decodes to
{"alg":"HS256","typ":"JWT"}. - Payload – JSON with the claims: statements about the user and the token itself.
- Signature – bytes computed from the first two parts and a key. It is not JSON and does not decode to anything readable.
Each part uses base64url: the URL-safe Base64 alphabet with - and _, and no = padding. That is why almost every JWT starts with eyJ: it is the encoding of {".
Decoding by hand
You need no special tool. In a terminal:
echo 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' | base64 -d
{"alg":"HS256","typ":"JWT"}
The payload may need padding first. Its length must be a multiple of 4, so add one or two = signs, and swap - for + and _ for / if they appear. The sample payload decodes to:
{"sub":"demo-user-42","name":"Example Person","role":"reader",
"iat":1700000000,"exp":1700003600}
Reading the claims
| Claim | Meaning | In the sample |
|---|---|---|
sub | Subject: who the token is about | demo-user-42 |
iat | Issued at, in Unix seconds | 1700000000 = 2023-11-14 22:13:20 UTC |
exp | Expiry, in Unix seconds | 1700003600 = 2023-11-14 23:13:20 UTC |
nbf | Not valid before this time | (not set) |
iss, aud | Issuer and intended audience | (not set) |
Lifetime check: exp − iat = 1700003600 − 1700000000 = 3,600 seconds, so the sample was valid for exactly one hour. The timestamp guide explains the seconds-since-1970 format.
Decoding is not verifying
Anyone can change "role":"reader" to "role":"admin", re-encode the payload, and paste the old signature on the end. A decoder will happily show the forged claims. Only verification catches it: the server recomputes the signature over the header and payload with its key and compares. With HS256 that is an HMAC-SHA256 using a shared secret; with RS256 or ES256 the server checks a signature against a public key.
A correct verifier also:
- accepts only the algorithms it expects, and never
"alg":"none"; - rejects tokens past
expor beforenbf, allowing a small clock skew; - checks
issandaudso a token minted for another service is refused.
Common mistakes
- Putting secrets in the payload. It is encoded, not encrypted. Assume every claim is public.
- Trusting a decoded token in the browser. Front-end code may read claims to show a name, but every access decision belongs on the server after verification.
- Reading
expas milliseconds. JWT times are seconds. Multiply by 1,000 before passing them to JavaScript’sDate.
Questions
Can this page verify a signature?
No, by design. Verifying needs the key, and a secret key should never be typed into a web page. The tool only decodes and labels the signature as unverified.
Can I log a user out by deleting their JWT?
Deleting it on the client stops that browser from sending it, but a copy stays valid until exp. That is why access tokens are kept short-lived.