What Is a JWT? JSON Web Tokens Explained With Examples

The Most Common Misconception About JWTs

Every week on Stack Overflow, a developer stores a user's password in a JWT payload, ships it to production, and wonders why their app got owned. Here's the thing that trips people up: a JWT is not encrypted. It is signed. Those two words describe entirely different operations with entirely different security properties.

When you see a JWT like eyJhbGc..., you are looking at Base64Url-encoded text — the same encoding used to attach files to emails. Paste it into the Base64 decoder and you get readable JSON back in two seconds. The signature on a JWT does not hide data; it proves the token was issued by someone with the signing key and has not been tampered with since.

That distinction cleared up, JWTs are one of the most elegant solutions in modern auth: stateless, portable, and verifiable without a database round-trip. By 2026, the JWT standard (RFC 7519) underpins authentication for an estimated 85% of Fortune 500 APIs, according to an AppSec Master 2026 infrastructure analysis.

What Is a JWT Token?

A JSON Web Token (JWT) — pronounced "jot" — is an open standard (RFC 7519) that defines a compact, URL-safe format for securely transmitting claims between parties as a JSON object. A "claim" is a statement: "this token was issued for user 4521," or "this token expires at 1745000000."

The defining characteristic is self-containment. Unlike session tokens that require a server-side lookup to know who the user is, a JWT carries all necessary information inside itself. Any service with the right verification key can validate it — instantly and without network calls.

// A real JWT looks like this (line breaks added for readability):
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
.
eyJzdWIiOiJ1c2VyXzQ1MjEiLCJuYW1lIjoiQWxpY2UiLCJyb2xlIjoiYWRtaW4iLCJpYXQiOjE3MDk4NTIwMDAsImV4cCI6MTcwOTg1MjkwMH0
.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

// Three parts separated by dots:
// Part 1 — Header:    algorithm + token type
// Part 2 — Payload:   the actual claims (user data, expiry, etc.)
// Part 3 — Signature: cryptographic proof of authenticity

The header decodes to {"alg":"HS256","typ":"JWT"}. The payload decodes to a JSON object with your claims. The signature is a hash computed over the header + payload using your secret key. Change one character in the payload, the signature no longer matches — the token is rejected.

Paste any JWT into our JWT Decoder to inspect its parts in real time — it runs entirely in your browser.

The Three Parts of a JWT, In Depth

1. Header

The header specifies how the token is signed. It is a JSON object with two standard fields: alg (algorithm) and typ (type). This JSON is then Base64Url-encoded to produce the first segment of the JWT.

// Header JSON:
{
  "alg": "RS256",   // RSA with SHA-256 — asymmetric key pair
  "typ": "JWT"
}

// Base64Url-encoded → eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

// Algorithm options:
// HS256  — HMAC-SHA256  (symmetric — same key signs and verifies)
// RS256  — RSA-SHA256   (asymmetric — private signs, public verifies)
// ES256  — ECDSA-P256   (asymmetric — smaller key than RSA, same security)
// EdDSA  — Ed25519      (asymmetric — fastest verify, modern default)

2. Payload (Claims)

The payload contains claims. RFC 7519 defines three categories:

• Registered claims: standardized names with agreed-upon meanings (iss, sub, exp, etc.)
• Public claims: collision-resistant names registered in the IANA JWT Claims Registry
• Private claims: application-specific data both parties agree on

{
  // RFC 7519 registered claims
  "iss": "https://auth.example.com",    // issuer
  "sub": "user_4521",                   // subject (user ID)
  "aud": "https://api.example.com",     // audience (intended recipient)
  "exp": 1745852900,                    // expiration (Unix timestamp)
  "nbf": 1745852000,                    // not valid before this time
  "iat": 1745852000,                    // issued at
  "jti": "a8f2c1d9-e3b7-4a10",         // unique JWT ID (for revocation/replay protection)

  // Private claims — your application-specific data
  "role": "admin",
  "tenant_id": "acme-corp",
  "permissions": ["reports:read", "users:write"]
}

3. Signature

The signature is the cryptographic guarantee. It is computed over base64Url(header) + "." + base64Url(payload) using the algorithm declared in the header.

// HS256 (symmetric — one secret used for both sign and verify):
signature = HMAC-SHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secretKey
)

// RS256 (asymmetric — private key signs, public key verifies):
signature = RSA-SHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  privateKey
)

// To verify: check that the computed signature matches the token's third segment
// If the payload was modified → signature mismatch → token rejected

Creating and Verifying a JWT: Real Code

Most languages have a well-maintained JWT library. Here is the full create-and-verify cycle in Node.js using the jose library (the most RFC-compliant option in 2026):

import { SignJWT, jwtVerify, generateSecret } from 'jose'

// 1. Generate a signing secret (do this once, store in env var)
const secret = await generateSecret('HS256')

// 2. Sign a JWT (e.g., after user logs in)
async function createAccessToken(userId: string, role: string): Promise<string> {
  return new SignJWT({ sub: userId, role })
    .setProtectedHeader({ alg: 'HS256' })
    .setIssuedAt()
    .setIssuer('https://auth.example.com')
    .setAudience('https://api.example.com')
    .setExpirationTime('15m')   // 15 minutes
    .sign(secret)
}

// 3. Verify a JWT on each request
async function verifyAccessToken(token: string) {
  const { payload } = await jwtVerify(token, secret, {
    issuer: 'https://auth.example.com',
    audience: 'https://api.example.com',
    algorithms: ['HS256'],  // explicit allowlist — never allow 'none'
  })
  return payload  // throws if invalid, expired, or tampered
}

// Usage in Express middleware:
app.use(async (req, res, next) => {
  const authHeader = req.headers.authorization
  if (!authHeader?.startsWith('Bearer ')) return res.status(401).json({ error: 'No token' })

  try {
    const token = authHeader.slice(7)
    req.user = await verifyAccessToken(token)
    next()
  } catch (err) {
    res.status(401).json({ error: 'Invalid or expired token' })
  }
})

For Python, the PyJWT library handles the same workflow:

import jwt
import datetime
import os

SECRET_KEY = os.environ['JWT_SECRET']

def create_access_token(user_id: str, role: str) -> str:
    payload = {
        'sub': user_id,
        'role': role,
        'iat': datetime.datetime.utcnow(),
        'exp': datetime.datetime.utcnow() + datetime.timedelta(minutes=15),
        'iss': 'https://auth.example.com',
        'aud': 'https://api.example.com',
    }
    return jwt.encode(payload, SECRET_KEY, algorithm='HS256')

def verify_access_token(token: str) -> dict:
    # PyJWT raises exceptions for expired/invalid/tampered tokens
    return jwt.decode(
        token,
        SECRET_KEY,
        algorithms=['HS256'],           # explicit allowlist
        audience='https://api.example.com',
        issuer='https://auth.example.com',
    )

Signing Algorithms Compared: HS256 vs RS256 vs ES256

Your choice of signing algorithm determines who can verify tokens and how — a critical architectural decision. According to a 2025 Veracode scan analysis, over 15% of production JWT implementations use mismatched algorithm configurations, creating exploitable vulnerabilities.

For microservices, RS256 is the pragmatic default. Your auth server keeps the private key secret. Every microservice fetches the public key from a JWKS endpoint (JSON Web Key Set) and caches it. No secret distribution problem, no risk of one compromised service leaking the signing key.

// Fetch and cache the JWKS (public keys) from your auth server
import { createRemoteJWKSet, jwtVerify } from 'jose'

const JWKS = createRemoteJWKSet(
  new URL('https://auth.example.com/.well-known/jwks.json')
)

// Any microservice verifies tokens using only the public keys:
const { payload } = await jwtVerify(token, JWKS, {
  issuer: 'https://auth.example.com',
  audience: 'https://api.example.com',
  algorithms: ['RS256'],
})

JWT vs Session Cookies vs API Keys

Understanding when to use JWTs starts with understanding the alternatives. Each approach makes a different tradeoff between statefulness, revocability, and complexity.

The revocation problem is the most important tradeoff. A session cookie can be invalidated immediately — delete the session from Redis and the user is logged out. A JWT, once issued, is valid until it expires. To revoke a JWT early, you need a token blocklist (Redis set of jti values), which adds a database lookup on every request — erasing the statefulness benefit. For most consumer web apps with logout requirements, short-lived JWTs (15 min) paired with a refresh token strategy is the pragmatic answer.

The Access Token + Refresh Token Pattern

Industry best practice is a two-token strategy, endorsed by the IETF OAuth Working Group in RFC 6749 and refined in the OAuth 2.0 Security Best Current Practice document:

• Access token: Short-lived JWT (5–15 minutes). Sent in every API request via Authorization: Bearer <token> header. Stored in memory (JS variable), never in localStorage.
• Refresh token: Long-lived opaque token (7–30 days). Stored in an HttpOnly; Secure; SameSite=Strict cookie. Used only to obtain new access tokens from the auth endpoint.

// Client-side token refresh (React example with automatic retry):
let accessToken: string | null = null

async function apiFetch(url: string, options: RequestInit = {}) {
  if (!accessToken) {
    accessToken = await refreshAccessToken()
  }

  const response = await fetch(url, {
    ...options,
    headers: {
      ...options.headers,
      Authorization: `Bearer ${accessToken}`,
    },
  })

  if (response.status === 401) {
    // Access token expired — refresh and retry once
    accessToken = await refreshAccessToken()
    return fetch(url, {
      ...options,
      headers: { ...options.headers, Authorization: `Bearer ${accessToken}` },
    })
  }

  return response
}

async function refreshAccessToken(): Promise<string> {
  const res = await fetch('/api/auth/refresh', {
    method: 'POST',
    credentials: 'include',  // sends HttpOnly refresh token cookie
  })
  if (!res.ok) throw new Error('Session expired — please log in again')
  const { accessToken } = await res.json()
  return accessToken
}

Implement refresh token rotation: each time a refresh token is used, issue a new one and immediately invalidate the old one. If an attacker steals the refresh token and uses it after the legitimate client has already rotated it, the server sees the reuse attempt and can invalidate all tokens for that user. This pattern is described in the OAuth Security Best Current Practice draft.

Critical JWT Security Vulnerabilities

A 2025 PortSwigger analysis found that 28% of JWT-related breaches stemmed from algorithm confusion and misimplementation — not from cryptographic weaknesses. These are the three attacks every developer must understand:

1. The alg:none Attack

If your library accepts the "none" algorithm, an attacker can forge a token by setting {"alg":"none"} and stripping the signature. The library skips verification because "no signature needed." Fix: explicitly allowlist algorithms in your verification call. Never accept "none".

2. Algorithm Confusion (RS256 → HS256)

When a server expects RS256 but a library accepts any algorithm, an attacker can switch the header to HS256 and sign the token with the server's public key (which is public). The server then verifies the HS256 signature using its public key — and succeeds. Fix: always pin the expected algorithm server-side.

3. Weak Secrets

HS256 secrets shorter than 256 bits are brute-forceable offline. If an attacker captures a JWT, they can attempt offline dictionary attacks. The JWT spec recommends at minimum a 256-bit (32-byte) random secret. Generate it properly:

# Generate a secure 256-bit secret (Node.js):
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Or with OpenSSL:
openssl rand -hex 32

# Store it in an environment variable — NEVER hardcode in source code:
JWT_SECRET=a3f8c1d9e2b74f10a5e7c3d8b2f19e4a...

Where to Store JWT Tokens on the Client

The recommendation from the OWASP Authentication Cheat Sheet: store access tokens in memory, refresh tokens in HttpOnly cookies. The memory approach means tokens are lost on page refresh — solved by triggering a silent refresh on app load using the refresh token cookie.

When Not to Use JWTs

JWTs are not always the right tool. Redis argues they are outright dangerous for user sessions. Here are the cases where session cookies win:

• Instant logout requirements: If users must be immediately logged out on password change or account suspension, you need server-side sessions or a blocklist — both negate JWT's stateless advantage.
• Traditional server-rendered apps: A Rails or Django app with sticky sessions has no reason to switch to JWTs. The complexity buys nothing.
• Storing large payloads: Every JWT is sent on every request. A 2KB payload on 1,000 req/s is 2MB/s of extra bandwidth per instance.
• Low-trust environments: If you can't guarantee HTTPS everywhere, don't use JWTs in Authorization headers. Use server-side sessions with Secure cookies.

JWT in the Wild: Real-World Architecture

Here is how a typical microservices JWT flow works end-to-end:

1. User logs in → Auth Service validates credentials
   Auth Service issues:
     - Access JWT (RS256, 15 min exp) → sent to client in JSON body
     - Refresh token (opaque) → sent as HttpOnly cookie

2. Client stores access token in memory
   Every API call: Authorization: Bearer <access_token>

3. API Gateway / each microservice:
   - Fetches public key from https://auth.example.com/.well-known/jwks.json
   - Verifies signature, issuer, audience, expiry
   - No database call needed — verification is pure CPU work

4. When access token expires (after 15 min):
   - Client calls POST /api/auth/refresh (with cookie)
   - Auth Service validates refresh token → issues new access token
   - Optionally rotates refresh token (new one in new cookie)

5. On logout:
   - Client clears in-memory access token
   - Server adds refresh token to blocklist (Redis TTL = token TTL)
   - Access token expires naturally within 15 min

Frequently Asked Questions

JWT Quick-Reference Checklist