JSON Web Tokens (JWT) Explained: Structure, Use Cases, and Security

By Deepak Kumar Developer & builder of JSON Formatter Hub · About the author

May 2025 · Published by JSON Formatter Hub · Report an issue

A JSON Web Token (JWT) is a compact, URL-safe way to transmit claims between two parties. It is used almost universally for API authentication — when a user logs in, the server issues a JWT; the client stores it and sends it with every subsequent request. The server verifies the token's signature without looking anything up in a database. Understanding exactly how JWTs work — and where they go wrong — is essential for any developer building an API.

The Three-Part Structure

A JWT looks like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFsaWNlIiwiaWF0IjoxNzE1MzM2MDAwLCJleHAiOjE3MTUzMzk2MDB9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Three base64url-encoded sections, separated by dots: header.payload.signature.

Part 1: Header

Decode the first section and you get a JSON object describing the token type and signing algorithm:

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

Common algorithms: HS256 (HMAC-SHA256, symmetric — one shared secret), RS256 (RSA-SHA256, asymmetric — private key signs, public key verifies).

Part 2: Payload (Claims)

The payload carries the actual data — called claims:

{
  "sub": "1234567890",
  "name": "Alice",
  "email": "alice@example.com",
  "role": "admin",
  "iat": 1715336000,
  "exp": 1715339600,
  "iss": "https://auth.example.com",
  "aud": "https://api.example.com"
}

Standard registered claims:

• sub — subject (usually a user ID)
• iat — issued at (Unix timestamp)
• exp — expiration time (Unix timestamp)
• iss — issuer (who created the token)
• aud — audience (who should accept the token)
• nbf — not before (token is invalid before this time)

Part 3: Signature

The signature is computed over the encoded header and payload using the algorithm and secret:

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

The signature cannot be forged without the secret. If the payload is tampered with, the signature will not match and the token is rejected. Note: the payload is encoded, not encrypted — anyone can read it by base64-decoding it.

How to Decode a JWT (Without Verifying)

To inspect a token's payload for debugging (do not rely on this for authorization):

// JavaScript — decode without verifying signature
function decodeJWT(token) {
  const parts = token.split('.');
  if (parts.length !== 3) throw new Error('Invalid JWT');
  const payload = parts[1].replace(/-/g, '+').replace(/_/g, '/');
  return JSON.parse(atob(payload));
}

const claims = decodeJWT('eyJhbGci...');
console.log(claims.sub);  // user ID
console.log(new Date(claims.exp * 1000)); // expiry date

Creating and Verifying JWTs

JavaScript (jsonwebtoken library)

const jwt = require('jsonwebtoken');

const SECRET = process.env.JWT_SECRET; // store in env, never hardcode

// Sign a token (expires in 1 hour)
const token = jwt.sign(
  { sub: user.id, name: user.name, role: user.role },
  SECRET,
  { expiresIn: '1h', issuer: 'https://auth.example.com' }
);

// Verify and decode
try {
  const payload = jwt.verify(token, SECRET, {
    issuer: 'https://auth.example.com'
  });
  console.log(payload.sub);
} catch (err) {
  // TokenExpiredError, JsonWebTokenError, NotBeforeError
  console.error('Invalid token:', err.message);
}

Python (PyJWT library)

import jwt
from datetime import datetime, timedelta, timezone

SECRET = 'your-secret-key'

# Sign
payload = {
    'sub': str(user.id),
    'name': user.name,
    'iat': datetime.now(timezone.utc),
    'exp': datetime.now(timezone.utc) + timedelta(hours=1)
}
token = jwt.encode(payload, SECRET, algorithm='HS256')

# Verify
try:
    decoded = jwt.decode(token, SECRET, algorithms=['HS256'])
    print(decoded['sub'])
except jwt.ExpiredSignatureError:
    print('Token expired')
except jwt.InvalidTokenError as e:
    print(f'Invalid token: {e}')

HS256 vs RS256: Which to Use

Security Pitfalls

The "alg: none" attack

Early JWT libraries accepted tokens with "alg": "none" and no signature, treating them as valid. Always explicitly specify which algorithms you accept when verifying — never pass an empty or wildcard list:

// WRONG — accepts any algorithm including "none"
jwt.verify(token, secret);

// CORRECT — whitelist the expected algorithm
jwt.verify(token, secret, { algorithms: ['HS256'] });

localStorage vs httpOnly cookie

Storing a JWT in localStorage makes it readable by any JavaScript on the page, including injected scripts (XSS). Storing it in an httpOnly cookie means JavaScript cannot read it, but you must also set SameSite=Strict or SameSite=Lax to prevent CSRF. For most applications, httpOnly cookies are safer.

Keep expiry short, use refresh tokens

A stolen JWT cannot be invalidated (JWTs are stateless). Short-lived access tokens (15 minutes to 1 hour) combined with longer-lived refresh tokens minimize the damage window. The refresh token is stored securely and exchanged for a new access token when needed.

Validate iss and aud claims

Always verify iss (issuer) and aud (audience) in addition to the signature and expiry. A token issued by one service should not be accepted by another service even if the signature is valid.

What NOT to store in a JWT payload

The payload is base64-encoded, not encrypted — anyone with the token can read it. Never put passwords, credit card numbers, social security numbers, or other sensitive PII in the payload. Store only non-sensitive identifiers and permissions.

Complete Authentication Flow with JWT

Here is how a typical stateless login system works end-to-end using JWTs:

1. User submits credentials — the client sends username and password to POST /auth/login.
2. Server validates credentials — checks the password hash in the database.
3. Server issues tokens — returns a short-lived access token (15–60 min) and a long-lived refresh token (7–30 days).
4. Client stores tokens — access token in memory or a session variable; refresh token in an httpOnly cookie.
5. Client sends the access token — every API request includes Authorization: Bearer <access_token>.
6. Server verifies the token — checks signature, expiry, issuer, and audience. No database call needed.
7. Access token expires — the client sends the refresh token to POST /auth/refresh to get a new access token.
8. User logs out — the client discards the access token; the server invalidates the refresh token in a revocation store (database or Redis).

The Refresh Token Pattern

Because JWTs cannot be revoked before they expire, a short access token lifetime limits the damage from a stolen token. The refresh token handles silent re-authentication:

Node.js — issuing both tokens

const jwt = require('jsonwebtoken');

const ACCESS_SECRET  = process.env.ACCESS_TOKEN_SECRET;
const REFRESH_SECRET = process.env.REFRESH_TOKEN_SECRET;

function issueTokens(userId, role) {
  const accessToken = jwt.sign(
    { sub: userId, role },
    ACCESS_SECRET,
    { expiresIn: '15m', issuer: 'https://auth.example.com' }
  );

  const refreshToken = jwt.sign(
    { sub: userId },
    REFRESH_SECRET,
    { expiresIn: '7d', issuer: 'https://auth.example.com' }
  );

  return { accessToken, refreshToken };
}

// Refresh endpoint
app.post('/auth/refresh', (req, res) => {
  const token = req.cookies.refreshToken; // httpOnly cookie
  if (!token) return res.status(401).json({ error: 'No refresh token' });

  try {
    const payload = jwt.verify(token, REFRESH_SECRET, {
      issuer: 'https://auth.example.com'
    });
    // Optionally: check token is not in a revocation list
    const { accessToken } = issueTokens(payload.sub, payload.role);
    res.json({ accessToken });
  } catch (err) {
    res.status(403).json({ error: 'Invalid or expired refresh token' });
  }
});

JWT Revocation Strategies

JWTs are stateless by design — there is no built-in way to invalidate a token before it expires. These are the practical patterns used in production:

• Short expiry — the simplest strategy. If access tokens expire in 15 minutes, a stolen token is only useful for 15 minutes at most.
• Refresh token revocation list — store refresh token IDs (the jti claim) in Redis or a database. On each refresh request, check whether the token ID has been revoked. Log out by adding the ID to the revocation list. This is the most common approach.
• Token rotation — issue a new refresh token on every use and invalidate the old one. If a stolen refresh token is used, the legitimate user's next request will fail, alerting the system to the compromise.
• Version claim — store a tokenVersion integer on the user record in the database. Embed the version in the JWT. Verify it on each request. Increment the version to invalidate all existing tokens for that user (password reset, suspicious activity).

Common JWT Mistakes

Related Articles

• What Is JSON? — the JSON format that JWT is built on
• How to Parse JSON — JSON handling in multiple languages
• JSON FAQ — common JSON questions answered
• REST API JSON Best Practices — designing clean API responses