How to Decode JWT Tokens: Complete 2025 Developer Guide

You're debugging a 401 Unauthorized error. You have a JWT token from the Authorization header, but what's inside it? Is the token expired? Does it have the right claims? Is the algorithm correct? To answer these questions, you need to decode the JWT—and understand what you're looking at.

What is a JWT Token?

A JWT (JSON Web Token) is a compact, URL-safe way to represent claims to be transferred between two parties. It's the modern standard for authentication and authorization in web applications, APIs, and microservices.

JWT Structure Explained: The Three Parts

1. Header: Algorithm & Token Type

The header specifies the signing algorithm (HMAC SHA256, RSA, etc.) and token type (JWT).

{
  "alg": "HS256",    // Algorithm: HMAC SHA-256
  "typ": "JWT"       // Token type
}

2. Payload: Claims & User Data

The payload contains claims—statements about the user and additional metadata. There are three types of claims:

{
  // Registered claims
  "iss": "https://api.myapp.com",      // Issuer
  "sub": "user-12345",                 // Subject (user ID)
  "aud": "https://myapp.com",          // Audience
  "exp": 1732752000,                   // Expiration time (Unix)
  "iat": 1732748400,                   // Issued at (Unix)
  "nbf": 1732748400,                   // Not before

  // Public/custom claims
  "name": "John Doe",
  "email": "john@example.com",
  "roles": ["admin", "user"],
  "permissions": ["read:users", "write:posts"]
}

3. Signature: Verification & Integrity

The signature ensures the token hasn't been tampered with. It's created by:

1. Base64-encoding the header and payload
2. Concatenating them with a period: encodedHeader.encodedPayload
3. Signing the result with a secret key (HMAC) or private key (RSA)

Step-by-Step: How to Decode JWT Tokens

Method 1: ByteTools JWT Decoder (Recommended for Development)

Method 2: Command Line (jq + base64)

# Decode JWT header (first part)
echo "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" | base64 -d | jq

# Decode JWT payload (second part)
echo "eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIn0" | base64 -d | jq

# Decode both parts in one line
JWT="eyJhbGci...full.token.here"
echo $JWT | cut -d'.' -f1 | base64 -d | jq  # Header
echo $JWT | cut -d'.' -f2 | base64 -d | jq  # Payload

Method 3: JavaScript/Node.js

const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.xyz";

// Split JWT into parts
const [headerB64, payloadB64, signature] = jwt.split('.');

// Decode header
const header = JSON.parse(atob(headerB64));
console.log("Header:", header);

// Decode payload
const payload = JSON.parse(atob(payloadB64));
console.log("Payload:", payload);

// Check expiration
if (payload.exp && Date.now() >= payload.exp * 1000) {
  console.log("Token expired!");
}

Method 4: Python

import base64
import json

jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.xyz"

# Split and decode
header, payload, signature = jwt.split('.')

# Decode (add padding if needed)
def decode_jwt_part(part):
    padding = 4 - len(part) % 4
    part += '=' * padding
    return json.loads(base64.urlsafe_b64decode(part))

header_data = decode_jwt_part(header)
payload_data = decode_jwt_part(payload)

print("Header:", header_data)
print("Payload:", payload_data)

Common JWT Debugging Scenarios

Scenario 1: 401 Unauthorized - Token Expired

Scenario 2: Wrong User Data - Missing Permissions

Scenario 3: Algorithm Mismatch

Scenario 4: Wrong Issuer or Audience

JWT Security Best Practices

When to Decode vs. Verify JWT Tokens

Common JWT Claims Reference

Privacy & Security When Decoding JWTs Online

Frequently Asked Questions

Key Takeaways

Related Privacy-First Tools