What Is a JSON Web Token (JWT)? Explained Simply With Real Examples

A JSON Web Token (JWT) is a compact token that proves who you are. After you log in, the server creates a signed token containing your user ID, permissions, and expiration time. You send this token with every request. The server verifies the signature and knows who you are — without storing any session data.

If you have ever wondered what that long string of characters in your Authorization header is, or why your API uses "Bearer tokens," this is the explanation. No jargon, no unnecessary complexity — just how JWTs work in practice.

The 30-Second Explanation

Think of a JWT like a tamper-proof wristband at a music festival:

1. You show your ID at the gate (login with username + password)
2. The gate gives you a wristband (server creates a JWT)
3. The wristband has your info printed on it (JWT payload: name, ticket type, expiration)
4. The wristband has a tamper-proof seal (JWT signature: proves it was issued by the gate, not forged)
5. You show the wristband at every stage (send JWT with every API request)
6. Security checks the seal, not a database (server verifies the signature, does not need to look anything up)

That is JWT authentication. The token carries your identity. The signature proves it is authentic. The server is stateless.

What a JWT Actually Looks Like

A JWT is three Base64-encoded JSON objects separated by dots:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwicm9sZSI6ImFkbWluIiwiZXhwIjoxNzE3MDI3MjAwfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Decoded, the three parts are:

Part	Decoded Content	Purpose
Header	{"alg":"HS256","typ":"JWT"}	Tells the server which algorithm was used to sign
Payload	{"sub":"1234567890","name":"John Doe","role":"admin","exp":1717027200}	The actual data — user identity and permissions
Signature	HMACSHA256(header + "." + payload, secret)	Proves the token was not modified and was issued by the trusted server

JWT vs Session Cookies vs API Keys

Three common authentication methods, and when each makes sense:

Feature	JWT (Bearer Token)	Session Cookie	API Key
State	Stateless — all data in the token	Stateful — session stored on server	Stateless — key is the credential
Storage	Client stores token (localStorage, cookie, memory)	Server stores session (Redis, DB, memory)	Client stores key (env var, config)
Scalability	\u2713 No shared state between servers	~Requires shared session store across servers	\u2713 No shared state
Revocation	\u2717 Hard — token valid until expiration	\u2713 Easy — delete session from store	\u2713 Easy — delete key from database
Size	~200-800 bytes (grows with claims)	~32 bytes (just a session ID)	~32-64 bytes
Cross-domain	\u2713 Works across domains (Authorization header)	\u2717 Cookies are domain-scoped	\u2713 Works across domains
Best for	APIs, microservices, mobile apps, SPAs	Traditional web apps, server-rendered pages	Server-to-server, third-party integrations
Security risks	Token theft, no revocation without infra	Session fixation, CSRF (mitigated with SameSite)	Key theft, no built-in expiration

The JWT Authentication Flow

Here is the complete flow from login to authorized API request:

1. Login: User sends username + password to POST /auth/login
2. Server validates: Server checks credentials against the database
3. Token created: Server creates a JWT with user claims (ID, role, exp) and signs it with the secret key
4. Token returned: Server sends the JWT to the client in the response body
5. Client stores: Client saves the JWT (commonly in localStorage, sessionStorage, or an httpOnly cookie)
6. API request: Client includes the JWT in the Authorization header: Authorization: Bearer eyJhbG...
7. Server verifies: Server checks the JWT signature and reads the claims. If valid, processes the request.
8. Token expires: After the exp time, the token is rejected. Client must log in again or use a refresh token.

Registered Claims — The Standard Fields

Claim	Name	Required?	What It Does
sub	Subject	Recommended	Identifies who the token is about (user ID)
iss	Issuer	Recommended	Identifies who created the token (your auth server URL)
aud	Audience	Recommended	Identifies who the token is for (your API URL)
exp	Expiration	Recommended	Unix timestamp when the token expires
iat	Issued At	Optional	Unix timestamp when the token was created
nbf	Not Before	Optional	Token is not valid before this timestamp
jti	JWT ID	Optional	Unique identifier — useful for one-time-use tokens

Beyond these, you can add any custom claims: email, name, role, org_id, permissions, plan_tier — anything your application needs to know about the user without making a database call.

Common JWT Mistakes

• Storing sensitive data in the payload: JWTs are signed, not encrypted. Anyone can read the payload. Never put passwords, credit card numbers, or secrets in a JWT.
• Setting expiration too long: A 30-day JWT means a stolen token is valid for 30 days with no way to revoke it. Use short expirations (15-60 minutes) with refresh tokens.
• Not verifying on the server: Client-side JWT checks are for UX only. The server must verify the signature on every request. Decode is not verify.
• Using the "none" algorithm: Some libraries allow alg: "none" which means no signature. An attacker can send a token with alg: "none" and an arbitrary payload. Always whitelist allowed algorithms in your verification configuration.
• Storing in localStorage without XSS protection: If your site has an XSS vulnerability, an attacker can read localStorage and steal JWTs. Consider httpOnly cookies or memory-only storage for high-security applications.

Pair These Tools Together

• JWT Decoder — paste any JWT and see the header, payload, and expiration
• Base64 Encoder Decoder — understand the Base64 encoding behind JWTs
• JSON Formatter — format JWT payload JSON for readability
• Timestamp Converter — convert exp and iat Unix timestamps to human dates
• Hash Generator — explore the hashing algorithms used in JWT signatures
• URL Encoder — encode JWTs for safe URL transmission
• Password Generator — generate strong secrets for JWT signing

Honest Limitations

JWTs are not a universal authentication solution. They add complexity compared to session cookies for traditional web apps. They cannot be revoked without additional infrastructure (blacklists, short expiration + refresh tokens). They grow in size as you add claims, increasing bandwidth on every request. And they require careful security practices — algorithm validation, proper storage, signature verification. For simple web apps with server-side rendering, session cookies are often simpler and more secure. JWTs shine in distributed systems, APIs, and cross-domain authentication scenarios.