What Is a JWT Token? A Developer's Guide to JSON Web Tokens

JSON Web Tokens (JWTs) are everywhere in modern web development. If you've built or consumed an API in the last few years, you've almost certainly encountered them. But what exactly are they, and how do they work?

JWT in 30 Seconds

A JWT is a compact, URL-safe way to represent claims between two parties. In plain English: it's a string that contains information (like "this user is Alice and she's an admin") that can be verified and trusted.

A JWT looks like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFsaWNlIiwicm9sZSI6ImFkbWluIn0.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ

It's three Base64-encoded parts separated by dots: Header, Payload, and Signature.

The Three Parts

1. Header

The header specifies the token type and signing algorithm:

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

Common algorithms: HS256 (HMAC-SHA256), RS256 (RSA-SHA256), ES256 (ECDSA-SHA256).

2. Payload

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

{
  "sub": "1234567890",
  "name": "Alice",
  "role": "admin",
  "iat": 1516239022,
  "exp": 1700000000
}

Standard claims include:

• sub (subject) — who the token is about
• iat (issued at) — when the token was created
• exp (expiration) — when the token expires
• iss (issuer) — who created the token
• aud (audience) — who the token is intended for

You can add any custom claims you need (role, permissions, email, etc.).

3. Signature

The signature is created by combining the encoded header and payload with a secret key:

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

The signature ensures the token hasn't been tampered with. Anyone can read a JWT (it's just Base64), but only someone with the secret key can create a valid signature.

How JWT Authentication Works

Here's the typical flow:

1. Login: User sends credentials (username/password) to the server
2. Token creation: Server verifies credentials and creates a JWT containing user info
3. Token storage: Client stores the JWT (usually in memory or an httpOnly cookie)
4. Authenticated requests: Client includes the JWT in the Authorization header: Authorization: Bearer <token>
5. Verification: Server verifies the JWT signature and extracts user info from the payload

The key benefit: the server doesn't need to store session state. The JWT itself contains all the information needed to authenticate the user.

When to Use JWTs

Good use cases:

• Stateless API authentication
• Single sign-on (SSO) across multiple services
• Short-lived tokens for specific operations
• Service-to-service authentication in microservices

Bad use cases:

• Long-lived sessions (use server-side sessions instead)
• Storing sensitive data (JWTs are encoded, not encrypted)
• As a replacement for cookies in all cases

Common Security Pitfalls

1. Not Validating the Algorithm

Always validate the alg header. An attacker can change it to none to bypass signature verification. Most JWT libraries have this protection built in, but verify your library does.

2. Storing Secrets in the Payload

Remember: anyone can decode a JWT. Never put passwords, API keys, or sensitive data in the payload. The signature prevents tampering, but doesn't prevent reading.

3. Not Setting Expiration

Always set exp. A JWT without expiration is valid forever — if it's leaked, there's no way to invalidate it (without maintaining a blocklist, which defeats the purpose of stateless tokens).

4. Storing JWTs in localStorage

localStorage is accessible to any JavaScript on the page, making it vulnerable to XSS attacks. Prefer httpOnly cookies or in-memory storage.

Decoding JWTs

Need to inspect a JWT? You can decode the header and payload (they're just Base64) without the secret key. This is useful for debugging.

Try our JWT Decoder — it runs entirely in your browser, so your tokens stay private.

Decode and inspect JWT tokens safely with devformat.tools JWT Decoder — no data sent to any server.