What is a JWT? A Developer Guide to JSON Web Tokens

Learn how JSON Web Tokens work, their structure, use cases, and common pitfalls.

Last updated: 2026-03-05

A JSON Web Token (JWT) is a compact, URL-safe token used to securely transmit information between parties. It is most commonly used for authentication — once a user logs in, the server issues a JWT that the client sends with every subsequent request.

Structure

A JWT is three Base64URL-encoded parts separated by dots:

text

header.payload.signature

Header

Specifies the token type (JWT) and the signing algorithm (e.g. HS256, RS256).

json

{ "alg": "HS256", "typ": "JWT" }

Payload

Contains claims — statements about the user and metadata. Standard claims include sub (subject), iat (issued at), and exp (expiry).

json

{ "sub": "user_123", "role": "admin", "exp": 1735689600 }

Signature

Created by signing the encoded header and payload with a secret (symmetric) or private key (asymmetric). This prevents tampering.

text

HMACSHA256(base64url(header) + "." + base64url(payload), secret)

How Authentication Works

User sends credentials to the server
Server validates and returns a signed JWT
Client stores the JWT (memory, localStorage, or httpOnly cookie)
Client sends the JWT in the Authorization: Bearer <token> header
Server verifies the signature on every request — no session lookup needed

Signing Algorithms

Algorithm	Type	Use case
HS256	Symmetric (HMAC)	Single-service auth, shared secret
RS256	Asymmetric (RSA)	Multi-service, public key verification
ES256	Asymmetric (ECDSA)	Compact keys, mobile/IoT

Common Pitfalls

Do not store sensitive data in the payload. The payload is only Base64URL-encoded, not encrypted — anyone can decode it.
Always verify the signature server-side. Never trust a JWT that hasn't been verified.
Set an expiry (exp). Without it, a stolen token is valid forever.
Beware of the alg: none attack. Libraries that accept unsigned tokens are vulnerable. Always specify the expected algorithm.
Revocation is hard. JWTs are stateless — you can't invalidate one without a blocklist. Use short expiries and refresh tokens for sensitive apps.

Try the tools: JWT Debugger to inspect, decode, and build tokens.

Frequently Asked Questions

Is it safe to decode a JWT in the browser?

Yes. The header and payload of a JWT are just Base64URL-encoded JSON — they are not encrypted. Decoding reveals the claims but does not compromise security. The signature is what protects the token from tampering.

What are the three parts of a JWT?

A JWT has three Base64URL-encoded parts separated by dots: the header (algorithm and type), the payload (claims like sub, exp, iat), and the signature (cryptographic proof that the token was not tampered with).

What is the difference between JWT and session-based auth?

Sessions store state on the server (typically in a database or memory). JWTs are stateless — the token itself contains all the information the server needs. JWTs scale better horizontally but cannot be revoked without additional infrastructure.

Should I store JWTs in localStorage or cookies?

HttpOnly cookies are generally safer because they are not accessible to JavaScript, protecting against XSS attacks. localStorage is simpler but vulnerable to XSS. For most web applications, HttpOnly cookies with the Secure and SameSite flags are recommended.

Was this helpful?

Stay up to date

Get notified about new guides, tools, and cheatsheets.