What a JWT is
A JSON Web Token (JWT, pronounced “jot”) is a compact string that carries claims, which are statements about a user or a session, in a form that can be checked for tampering. It is widely used for API authentication and for passing identity between services.
The three parts
A JWT is three Base64URL strings joined by dots: header.payload.signature.
eyJhbGciOiJIUzI1NiJ9 . eyJzdWIiOiIxMjMifQ . 5mhBHqs5_DTLdINd9p5m7ZJ6XD0Xc55kIaRRyhPjhhE
- Header: JSON that names the signing algorithm (
alg) and token type. - Payload: JSON with the claims.
- Signature: a value computed from the first two parts and a secret or private key, so any change to the header or payload breaks it.
Standard claims
| Claim | Meaning |
|---|---|
| iss | Issuer of the token |
| sub | Subject: usually the user ID |
| aud | Audience: who the token is meant for |
| exp | Expiry time in Unix seconds |
| nbf | Not valid before this time |
| iat | Time the token was issued |
| jti | Unique ID of the token |
Applications add their own claims, such as roles. Time claims are Unix timestamps, explained in Unix timestamp explained.
Decoding is not verifying
Anyone can decode a JWT, because Base64URL is an encoding, not encryption (see Base64 is not encryption). The JWT Decoder reads the header and payload and shows whether the token has expired by your device clock. It does not verify the signature, and decoded data must never be trusted on that basis.
Verification happens on the server that receives the token:
- HS256: the same shared secret signs and verifies.
- RS256 or ES256: a private key signs, and a public key verifies, so many services can verify without being able to issue tokens.
Common mistakes
- Accepting
alg: none. An unsigned token is not proof of anything. Fix the allowed algorithms on the server instead of trusting the header. - Skipping claim checks. Verify
exp, and checkissandaudmatch what you expect. - Putting secrets in the payload. The payload is readable by anyone who has the token.
- Very long expiry. A stolen token works until it expires. Use short lifetimes and refresh tokens.
- Weak shared secrets. An HS256 secret must be long and random.
- Treating a JWT as a session you can revoke. Without extra state, you cannot cancel a token before it expires.
Where to keep tokens in a browser
Both choices have trade-offs. Local storage is readable by any script on the page (an XSS risk), while cookies with HttpOnly, Secure, and a suitable SameSite value are hidden from scripts but need protection against cross-site request forgery.
FAQ
Is a JWT encrypted?
A standard signed JWT is not. Encrypted tokens (JWE) exist but have five parts and a different structure.
Why does my token say expired?
exp is in the past by your device clock. Check the clock, or request a new token.
Can I read a token I do not trust?
Yes, decoding is harmless. Just do not act on its contents until the signature is verified.