What is a JWT Token? Understanding JSON Web Tokens

What is a JWT and Why Should You Care?

A JSON Web Token (JWT, pronounced "jot") is a compact, URL-safe way to represent claims between two parties. In practical terms, it is the mechanism behind most modern authentication systems. When you log into a web application and stay logged in across page reloads, there is a good chance a JWT is doing the work.

JWTs replaced older approaches like server-side sessions for many use cases because they are stateless. The server does not need to store session data — all the information it needs is encoded directly in the token. This makes JWTs particularly well-suited for distributed systems, microservices, and APIs where sharing session state across servers is impractical.

The standard is defined in RFC 7519 and has been widely adopted since its publication in 2015.

The Three Parts of a JWT

Every JWT consists of three Base64URL-encoded segments separated by dots:

xxxxx.yyyyy.zzzzz

1. Header

The header declares the token type and the signing algorithm:

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

Common algorithms include HS256 (HMAC with SHA-256), RS256 (RSA with SHA-256), and ES256 (ECDSA with P-256).

2. Payload

The payload contains the claims — statements about the user and additional metadata:

{"sub": "1234567890", "name": "Jane Doe", "iat": 1516239022, "exp": 1516242622}

Standard claims include sub (subject), iat (issued at), exp (expiration), iss (issuer), and aud (audience). You can add any custom claims you need.

3. Signature

The signature is created by taking the encoded header, the encoded payload, a secret key, and the algorithm specified in the header. For HS256:

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

The signature prevents tampering. If anyone modifies the payload (for example, changing the user ID), the signature verification fails and the token is rejected.

You can inspect and decode any JWT using our JWT Decoder — paste a token to see its header, payload, and signature details instantly.

How JWT Authentication Works

The typical flow for JWT-based authentication follows these steps:

1. Login: The user submits credentials (email and password) to the server.
2. Token creation: The server validates the credentials, creates a JWT containing the user's ID and relevant claims, signs it with a secret key, and sends it back to the client.
3. Storage: The client stores the token — usually in memory, localStorage, or an HttpOnly cookie.
4. Subsequent requests: The client includes the token in the Authorization header: Authorization: Bearer eyJhbGci...
5. Verification: The server verifies the signature and checks the expiration. If valid, the request proceeds. If not, the server returns a 401 Unauthorized response.

No database lookup is needed to verify the token — the server only needs the signing secret. This is what makes JWTs stateless and scalable.

Security Best Practices

JWTs are secure when implemented correctly, but several common mistakes create vulnerabilities:

• Always validate the signature. Never decode a JWT and trust its claims without verifying the signature first. Libraries like jsonwebtoken (Node.js) and PyJWT (Python) handle this automatically when used correctly.
• Set short expiration times. Access tokens should expire in 15-60 minutes. Use refresh tokens (stored securely) to obtain new access tokens without forcing the user to log in again.
• Use strong secrets. For HMAC algorithms, use at least 256 bits of entropy. A short or guessable secret makes brute-force attacks feasible.
• Never store sensitive data in the payload. The payload is encoded, not encrypted. Anyone can decode it with a Base64 decoder. Do not put passwords, credit card numbers, or confidential data in claims.
• Prefer RS256 over HS256 for public APIs. RS256 uses asymmetric keys — the private key signs and the public key verifies. This way, API consumers can verify tokens without knowing your signing secret.
• Store tokens securely on the client. HttpOnly cookies are more secure than localStorage because they are not accessible to JavaScript, reducing the risk of XSS-based token theft.

Common JWT Use Cases

• API authentication: The most common use. After login, every API request carries the JWT to identify the caller.
• Single Sign-On (SSO): A central identity provider issues JWTs that multiple applications accept, letting users log in once across services.
• Information exchange: JWTs can carry structured data between services. The signature ensures the data has not been tampered with in transit.
• Password reset links: A JWT embedded in a reset URL can carry the user ID and an expiration time, eliminating the need to store reset tokens in a database.
• Email verification: Similar to password resets — the token in the verification link confirms the email owner and expires after a set period.

To inspect tokens during development, paste them into our JWT Decoder. For encoding data in other formats, see our guide on Base64 encoding.

JWT vs Server-Side Sessions

JWTs are not a universal replacement for sessions. Each approach has trade-offs:

• Scalability: JWTs win. No shared session store needed across servers.
• Revocation: Sessions win. You can delete a session from the database instantly. Revoking a JWT before expiration requires maintaining a blacklist, which partially defeats the stateless advantage.
• Size: Sessions win. A session ID is a small string. A JWT can be 800+ bytes depending on claims, which adds overhead to every request.
• Simplicity: Sessions win for simple applications. JWT adds complexity (key management, token refresh logic, secure storage).

For most modern applications — especially SPAs, mobile apps, and microservices — JWTs are the right choice. For simple server-rendered applications with a single backend, sessions remain perfectly valid.