Skip to content
ENID
Developer

What Is a JWT? Structure, Claims, and Common Mistakes

A clear explanation of JSON Web Tokens: the three parts, the standard claims, how they are verified, and the mistakes to avoid.

Published 3 min read

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
  1. Header: JSON that names the signing algorithm (alg) and token type.
  2. Payload: JSON with the claims.
  3. 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

ClaimMeaning
issIssuer of the token
subSubject: usually the user ID
audAudience: who the token is meant for
expExpiry time in Unix seconds
nbfNot valid before this time
iatTime the token was issued
jtiUnique 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 check iss and aud match 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.

Related guides

Enter to open, Esc to close

Scroll to Top