JWT Explained: JSON Web Tokens Guide

A comprehensive guide to understanding JSON Web Tokens (JWTs). Learn the structure, decode them using our free tool, or do it manually with code in JavaScript, Python, and other languages.

What is a JWT?

A JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. JWTs are commonly used for authentication and authorization in web applications and APIs. According to the Postman State of API Report, JWTs are the most widely used token format in modern API authentication, adopted by over 80% of OAuth 2.0 implementations.

How JWT Authentication Works

JWT authentication follows a stateless flow that eliminates the need for server-side session storage:

1. User logs in with credentials (username/password, OAuth provider, etc.)
2. Server validates credentials and creates a JWT containing user identity claims (sub, name, role)
3. Server signs the JWT with a secret key (HMAC) or private key (RSA/ECDSA)
4. Client stores the token (localStorage, sessionStorage, or httpOnly cookie)
5. Client sends the JWT with every subsequent request via the Authorization header: Bearer <token>
6. Server verifies the signature and expiry, then extracts user identity from the payload — no database lookup required

This stateless approach makes JWTs ideal for microservices architectures and distributed systems where a centralized session store would be a bottleneck or single point of failure.

JWT Structure

A JWT consists of three parts separated by dots (.):

header.payload.signature

Here is a real-world example:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

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

{"sub": "1234567890", "name": "John Doe", "iat": 1516239022}

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

Standard JWT Claims (Registered Claims)

RFC 7519 defines a set of registered claim names that are not mandatory but recommended for interoperable JWTs:

Common JWT Signing Algorithms

Method 1: Decode JWT Using Our Free Online Tool

The easiest way to inspect a JWT is using our browser-based JWT Decoder tool. It runs entirely in your browser — no data is sent to any server:

1. Go to the JWT Decoder tool
2. Paste your JWT token into the input field
3. View the decoded header, payload, and signature instantly
4. Copy individual claims or the full decoded JSON

Method 2: Decode JWT in JavaScript

You can decode JWT tokens programmatically in JavaScript using the built-in atob() function:

function decodeJWT(token) {
  const parts = token.split(".");
  if (parts.length !== 3) throw new Error("Invalid JWT");

  const header = JSON.parse(atob(parts[0]));
  const payload = JSON.parse(atob(parts[1]));
  const signature = parts[2];

  return { header, payload, signature };
}

// Example usage
const token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" +
  ".eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ" +
  ".SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c";
const decoded = decodeJWT(token);
console.log("Header:", decoded.header);
console.log("Payload:", decoded.payload);

Method 3: Decode JWT in Python

Python requires handling base64 padding manually since the JWT format uses unpadded base64url encoding:

import json
import base64

def decode_jwt(token):
    parts = token.split(".")
    if len(parts) != 3:
        raise ValueError("Invalid JWT")

    def decode_part(part):
        # Add padding: JWT uses unpadded base64url
        padding = 4 - len(part) % 4
        if padding != 4:
            part += "=" * padding
        return json.loads(base64.urlsafe_b64decode(part))

    header = decode_part(parts[0])
    payload = decode_part(parts[1])
    signature = parts[2]
    return header, payload, signature

token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
header, payload, signature = decode_jwt(token)
print(json.dumps(payload, indent=2))

Method 4: Decode JWT in Node.js

In Node.js, use the built-in Buffer class which handles base64url natively:

function decodeJWT(token) {
  const [headerB64, payloadB64] = token.split(".");

  const decode = (str) =>
    JSON.parse(Buffer.from(str, "base64url").toString("utf-8"));

  return {
    header: decode(headerB64),
    payload: decode(payloadB64),
  };
}

const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";
console.log(decodeJWT(jwt));

How JWT Verification Works

Decoding a JWT only reads the base64-encoded data. Verification ensures the token has not been tampered with. The process differs by algorithm type:

JWT Security Best Practices

Following OWASP guidelines and industry standards, here are critical security practices for JWT implementation:

Common JWT Attacks and Mitigations

JWTs vs Alternative Authentication Approaches

Real-World JWT Usage Example

Here is a complete example of how a React application authenticates with a JWT-based API:

// Login: authenticate and store the JWT
async function login(email, password) {
  const res = await fetch("https://api.example.com/auth/login", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ email, password }),
  });

  const { token } = await res.json();

  // Store token (httpOnly cookie is more secure)
  localStorage.setItem("jwt", token);
  return token;
}

// Authenticated request: send JWT in Authorization header
async function fetchUserProfile() {
  const token = localStorage.getItem("jwt");

  const res = await fetch("https://api.example.com/users/me", {
    headers: {
      "Authorization": `Bearer ${token}`,
    },
  });

  if (res.status === 401) {
    // Token expired — redirect to login
    window.location.href = "/login";
    return null;
  }

  return res.json();
}

Frequently Asked Questions