JWT Decoder Guide: Understanding JSON Web Tokens

Published by Risetop · 10 min read · Updated April 2026

If you have spent any time in modern web development, you have almost certainly encountered JSON Web Tokens (JWTs). They are everywhere — authentication headers, API keys, OAuth flows, single sign-on systems. Yet many developers use them without fully understanding what is inside the token they are passing around. A JWT decoder peels back the layers of a token so you can inspect its headers, payload, and signature. In this guide, we will break down exactly how JWTs work, how to decode them, what each part means, and what security pitfalls to watch for.

What Is a JSON Web Token?

A JSON Web Token is a compact, URL-safe string that represents a set of claims (statements about an entity, typically the user). It is defined by RFC 7519 and has become the de facto standard for token-based authentication in web applications.

The structure is elegantly simple: three base64url-encoded segments separated by dots.

xxxxx.yyyyy.zzzzz

The three parts are:

• Header (xxxxx) — metadata about the token, including the signing algorithm
• Payload (yyyyy) — the actual data, called "claims"
• Signature (zzzzz) — cryptographic proof that the token has not been tampered with

This compact format is what makes JWTs so popular. They fit neatly into HTTP headers, URL parameters, and cookies. A typical JWT is only a few hundred characters long, yet it can carry rich structured data.

Anatomy of a JWT: Header, Payload, Signature

The Header

The header is a JSON object that tells the receiver how to process the token. It typically contains two fields:

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

• alg — the signing algorithm. Common values include HS256 (HMAC with SHA-256), RS256 (RSA with SHA-256), and ES256 (ECDSA with SHA-256).
• typ — the token type. Almost always JWT, but some implementations omit it.

When decoded, the header tells you exactly how the signature was generated, which is critical for verification.

The Payload

The payload contains the claims — the actual data the token carries. Claims come in three categories:

• Registered claims — standardized fields with predefined meanings:
  • iss (issuer) — who created the token
  • sub (subject) — who the token is about (usually the user ID)
  • aud (audience) — who the token is intended for
  • exp (expiration) — when the token expires (Unix timestamp)
  • nbf (not before) — when the token becomes valid
  • iat (issued at) — when the token was created
  • jti (JWT ID) — a unique identifier for the token
• Public claims — custom fields defined by you or the specification you are using (e.g., name, email, role)
• Private claims — custom fields agreed upon between the issuer and consumer, not standardized

{
  "sub": "user_12345",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "role": "admin",
  "iat": 1713139200,
  "exp": 1713225600
}

A common misconception is that JWT payloads are encrypted. They are not. Anyone who intercepts the token can decode the payload and read the claims. This is why you should never put sensitive information (passwords, credit card numbers, Social Security numbers) in a JWT payload.

The Signature

The signature is what makes a JWT tamper-proof. It is created by combining the header and payload with a secret key using the algorithm specified in the header.

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

When the server receives a token, it recomputes the signature using its own copy of the secret key. If the computed signature matches the one in the token, the payload has not been modified. If they do not match, the token has been tampered with and should be rejected.

For asymmetric algorithms like RS256, the server signs with a private key and the client verifies with the corresponding public key. This is particularly useful in microservice architectures where multiple services need to verify tokens without sharing a secret.

How to Decode a JWT

Decoding a JWT is straightforward because the header and payload are simply base64url-encoded. You can decode them in any programming language or even in your browser's console.

Using JavaScript

function decodeJWT(token) {
  const parts = token.split('.');
  const header = JSON.parse(atob(parts[0].replace(/-/g, '+').replace(/_/g, '/')));
  const payload = JSON.parse(atob(parts[1].replace(/-/g, '+').replace(/_/g, '/')));
  return { header, payload };
}

const result = decodeJWT('eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NSJ9.abc123');
console.log(result);

Using Python

import base64, json

def decode_jwt(token):
    parts = token.split('.')
    header = json.loads(base64.urlsafe_b64decode(parts[0] + '=='))
    payload = json.loads(base64.urlsafe_b64decode(parts[1] + '=='))
    return {'header': header, 'payload': payload}

Again, decoding is not verifying. These functions will happily decode a token with an invalid or missing signature. Verification requires the signing key and is typically done with a library like jsonwebtoken (Node.js), PyJWT (Python), or the native JWT handling in your framework.

JWT in Practice: Authentication Flow

Here is how JWTs typically work in a web application:

1. Login: The user submits credentials (username and password) to the server.
2. Token issuance: The server verifies the credentials and generates a JWT containing the user's identity and any relevant claims (role, permissions, etc.).
3. Token delivery: The server sends the JWT back to the client, typically in the response body or as an HTTP-only cookie.
4. Token storage: The client stores the token (in memory, localStorage, or a cookie) and includes it in the Authorization header of subsequent requests: Bearer <token>.
5. Token validation: The server receives the token, verifies the signature, checks the expiration, and processes the request based on the claims.

This stateless approach eliminates the need for server-side session storage, which is why JWTs are so popular in microservice architectures and single-page applications.

Common Security Pitfalls

JWTs are powerful, but they introduce security risks if used incorrectly. Here are the most common mistakes developers make:

• Using the "none" algorithm: Some JWT libraries accept "alg": "none", which means the token has no signature at all. Attackers can forge tokens by changing the algorithm to "none" and stripping the signature. Always validate that the algorithm matches what you expect.
• Weak signing secrets: For HMAC-based algorithms (HS256, HS384, HS512), the secret must be long and random — at least 256 bits. Using "secret", "password", or any short, guessable string makes brute-force attacks trivial.
• No expiration: Tokens without an exp claim are valid forever. Always set a reasonable expiration time. Short-lived access tokens (15–30 minutes) paired with longer refresh tokens are a common best practice.
• Storing sensitive data in the payload: Since the payload is just base64-encoded (not encrypted), anyone can decode it. Never put passwords, API keys, or personal data in a JWT.
• Using localStorage for tokens: localStorage is vulnerable to XSS attacks. Store tokens in HTTP-only, Secure, SameSite cookies whenever possible.
• Algorithm confusion attacks: An attacker might change the header from RS256 to HS256, causing the server to verify the RSA public key as an HMAC secret. Always explicitly check the algorithm on the server side.

When to Use JWT vs. Session Cookies

JWTs are not always the right choice. Here is a quick comparison:

• Use JWT when: You need stateless authentication, you have microservices that all need to verify tokens, you need to support cross-domain authentication, or you are building a mobile app that needs to manage its own auth state.
• Use session cookies when: You need server-side control over sessions (immediate revocation), you are building a traditional server-rendered application, or you want simpler security (cookies are sent automatically, no need to manage token storage).

In practice, many applications use a hybrid approach: short-lived JWTs for API authentication and server-side sessions for the web UI.

Frequently Asked Questions

Can anyone read the data inside a JWT?

Yes. The header and payload are base64url-encoded, which is encoding (not encryption). Anyone who intercepts the token can decode it and read the claims. This is by design — JWTs are meant to be self-contained and verifiable, not secret. If you need to protect the data, encrypt it separately or use JWE (JSON Web Encryption) instead of JWT.

What is the difference between JWS and JWE?

JWS (JSON Web Signature) is what most people mean when they say "JWT" — it provides integrity through a signature. JWE (JSON Web Encryption) provides confidentiality by encrypting the payload. A JWE token has five parts instead of three. Use JWS for authentication (you want to verify, not hide, the claims) and JWE when you need to keep the payload private.

How long should a JWT be valid?

Access tokens should be short-lived — 15 to 30 minutes is standard. This limits the damage if a token is compromised. Use a separate refresh token (stored in an HTTP-only cookie) to obtain new access tokens. Refresh tokens can have longer lifetimes (days or weeks) and should be validated against a server-side store to allow revocation.

What happens if a JWT is tampered with?

If the signature does not match, the server will reject the token. This is the entire point of the signature — it ensures that any modification to the header or payload is detected. An attacker cannot change the payload (e.g., changing "role": "user" to "role": "admin") without invalidating the signature, unless they also have access to the signing key.

Can I revoke a JWT?

Not directly, since JWTs are stateless — the server does not store them. This is a tradeoff. To implement revocation, you need to either maintain a blacklist of revoked token IDs (usually stored in Redis with TTL matching the token expiration), use short token lifetimes, or implement a hybrid approach where the server checks a revocation list alongside the token.

Is base64url the same as base64?

Almost, but with two differences: + is replaced with - and / is replaced with _. Also, the trailing = padding is removed. This makes the encoding URL-safe, which is necessary because JWTs are often transmitted in URLs and HTTP headers where special characters would cause problems.

Decode and Inspect with Confidence

Understanding JWTs is not optional for modern web developers — they are embedded in nearly every authentication system built in the last decade. Knowing how to decode and inspect a token helps you debug auth issues faster, write more secure code, and understand exactly what your application is sending and receiving.

Try Our Free JWT Decoder →

Paste any token, see the decoded header and payload instantly, and verify whether the signature is valid. Whether you are debugging an OAuth flow, inspecting an API response, or auditing your own authentication system, a reliable JWT decoder is an essential tool in your developer toolkit.