JWT Tokens Explained: What They Are and How to Decode Them
If you have ever logged into a web application, called a protected API, or implemented single sign-on, you have almost certainly encountered a JWT token — whether you realized it or not. JSON Web Tokens are one of the most widely used authentication mechanisms on the modern web, and understanding how they work is essential for any developer building secure applications.
Yet most developers treat JWTs as black boxes. They copy-paste a library, call jwt.sign(), and move on. That works until something breaks — until a token expires and users get locked out, until you find yourself debugging a 401 error at 2 AM, or until a security audit reveals that your tokens are leaking sensitive data in plaintext.
This guide explains everything you need to know about JWTs. What they are, how they are structured, how to decode them, when to use them, and what security pitfalls to avoid.
What Is a JWT Token
A JSON Web Token (JWT) is an open standard (RFC 7519) for securely transmitting information between parties as a compact, URL-safe JSON object. The information in a JWT can be verified and trusted because it is digitally signed.
JWTs can be signed using a secret key (with the HMAC algorithm) or a public/private key pair (using RSA or ECDSA). When a token is signed, the recipient can verify that the content has not been tampered with. When a token is encrypted, the content is also hidden from third parties.
The most common use case is authentication. After a user logs in, the server issues a JWT. The client stores this token (typically in memory or an HTTP-only cookie) and sends it with every subsequent request. The server validates the token's signature and extracts the user's identity without needing to query a database or maintain server-side session state.
This is fundamentally different from traditional session-based authentication, where the server stores session data and the client holds only a session ID. With JWTs, the token itself carries the information.
The Three Parts of a JWT
Every JWT consists of three parts, separated by dots:
xxxxx.yyyyy.zzzzz
Those three parts are the header, the payload, and the signature. Each part is Base64URL-encoded, which means you can decode them without any special tools — just a Base64 Encoder/Decoder will get you most of the way there, though a dedicated JWT Decoder handles the URL-safe variant and displays the result in a structured format.
Here is a real example of what a JWT looks like:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
That looks intimidating, but it is just three JSON objects encoded in Base64URL and concatenated with dots. Let us break each part down.
Part 1: The Header
The header typically contains two fields: the signing algorithm (alg) and the token type (typ).
{
"alg": "HS256",
"typ": "JWT"
}
This tells the recipient that the token is a JWT and was signed using HMAC-SHA256. Other common algorithms include RS256 (RSA with SHA-256), ES256 (ECDSA with SHA-256), and EdDSA (Edwards-curve Digital Signature Algorithm).
The header is Base64URL-encoded to produce the first part of the token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
Part 2: The Payload
The payload contains the claims — statements about the user and additional metadata. This is where the actual data lives.
{
"sub": "1234567890",
"name": "John Doe",
"email": "john@example.com",
"role": "admin",
"iat": 1516239022,
"exp": 1516242622
}
Claims fall into three categories:
Registered claims are predefined by the JWT specification. They are not mandatory but are recommended for interoperability:
iss(issuer) — who created the tokensub(subject) — who the token is about (usually a user ID)aud(audience) — who the token is intended forexp(expiration time) — when the token expires (Unix timestamp)nbf(not before) — the token is not valid before this timeiat(issued at) — when the token was createdjti(JWT ID) — a unique identifier for the token
Public claims are defined by the developer but should use collision-resistant names (often URIs) to avoid conflicts.
Private claims are custom claims agreed upon between parties, like role, permissions, or tenant_id.
Here is the critical thing to understand: the payload is not encrypted. It is only encoded. Anyone who has the token can decode the payload and read its contents. Never put sensitive information — passwords, credit card numbers, social security numbers — in a JWT payload.
Part 3: The Signature
The signature is what makes JWTs trustworthy. It is created by taking the encoded header, the encoded payload, and a secret key, then applying the algorithm specified in the header.
For HMAC-SHA256, the signature is computed like this:
HMACSHA256(
base64UrlEncode(header) + "." + base64UrlEncode(payload),
secret
)
The signature serves two purposes. First, it verifies that the token was issued by someone who knows the secret key. Second, it ensures the token has not been modified. If anyone changes a single character in the header or payload, the signature will not match, and the token will be rejected.
For asymmetric algorithms like RS256, the server signs the token with a private key and anyone can verify it with the corresponding public key. This is particularly useful in microservice architectures where multiple services need to verify tokens but only one service (the auth server) should be able to create them.
How JWT Authentication Works in Practice
Here is the typical flow when JWTs are used for authentication:
Step 1: The user sends their credentials (username and password) to the authentication endpoint.
Step 2: The server verifies the credentials. If valid, it creates a JWT containing the user's ID, roles, and an expiration time, then signs it with a secret key.
Step 3: The server sends the JWT back to the client.
Step 4: The client stores the token and includes it in the Authorization header of subsequent requests:
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Step 5: For each request, the server extracts the token from the header, verifies the signature, checks the expiration time, and extracts the user's identity from the payload.
You can test this entire flow using an API Tester to see how authorization headers work with real endpoints.
How to Decode a JWT Token
Decoding a JWT is straightforward because the payload is simply Base64URL-encoded, not encrypted. There are several ways to do it.
Using a Free Online Tool
The fastest way is to paste your token into a JWT Decoder. It will instantly split the token into its three parts, decode the header and payload, show the claims in a readable format, and display the expiration status.
Using JavaScript
function decodeJWT(token) {
const parts = token.split(".");
if (parts.length !== 3) {
throw new Error("Invalid JWT format");
}
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, signature: parts[2] };
}
Using Python
import base64
import json
def decode_jwt(token):
parts = token.split('.')
# Add padding if needed
payload = parts[1] + '=' * (4 - len(parts[1]) % 4)
decoded = base64.urlsafe_b64decode(payload)
return json.loads(decoded)
Using the Command Line
echo 'eyJzdWIiOiIxMjM0NTY3...' | \
tr '_-' '/+' | \
base64 -d 2>/dev/null | \
python3 -m json.tool
Remember: decoding is not the same as verifying. Anyone can decode a JWT. Only someone with the secret key can verify that it is authentic.
Common JWT Use Cases
API Authentication
JWTs are the standard for securing REST APIs. The client obtains a token after authenticating and includes it in every API request. The server validates the token without maintaining session state, making this approach highly scalable.
Single Sign-On (SSO)
JWTs enable SSO across multiple applications. A user logs in once with a central identity provider, receives a JWT, and can use that token to access any application that trusts the same issuer. This is how protocols like OAuth 2.0 and OpenID Connect work under the hood.
Microservice Communication
In a microservice architecture, services need to verify the identity of callers. JWTs work well here because each service can independently verify a token using the public key, without making a network call to the auth service.
Information Exchange
JWTs can be used to securely transmit information between parties. Because they can be signed, the recipient knows the sender is who they claim to be, and that the content has not been changed in transit.
Security Best Practices
JWTs are powerful but can be dangerous if misused. Follow these practices to avoid common pitfalls.
Keep Tokens Short-Lived
Set the exp claim to a short duration — 15 minutes for access tokens is a common choice. Use refresh tokens (stored securely, typically in HTTP-only cookies) to obtain new access tokens without requiring the user to log in again.
{
"sub": "user123",
"iat": 1711500000,
"exp": 1711500900
}
That token expires after 15 minutes. If it is stolen, the window of exploitation is limited.
Never Store Sensitive Data in the Payload
The payload is Base64URL-encoded, not encrypted. Anyone who intercepts the token can read its contents. Include only the minimum information needed — a user ID and role, not personal data.
Use Strong Signing Keys
For HMAC-based algorithms, use a key that is at least 256 bits long and generated with a cryptographically secure random number generator. Never use simple strings like "secret" or "my-jwt-key". You can use a Hash Generator to create strong, random keys.
Always Validate the Signature
Never skip signature verification. Some libraries have options to decode a token without verifying it — these should only be used for debugging, never in production.
Validate All Claims
Check not just the signature but also the exp, iss, aud, and nbf claims. A valid signature on an expired token should still result in rejection.
Use HTTPS Everywhere
JWTs transmitted over plain HTTP can be intercepted. Always use HTTPS in production. This is non-negotiable.
Choose the Right Algorithm
Prefer RS256 or ES256 over HS256 in production environments where multiple services need to verify tokens. With asymmetric algorithms, only the auth server needs the private key. If using HS256, the same secret must be shared with every service that verifies tokens, increasing the risk of key compromise.
Common JWT Vulnerabilities
The alg: none Attack
Some JWT libraries support an alg: none option, which means the token has no signature. An attacker can modify the payload, set the algorithm to none, remove the signature, and send the token to a server that does not properly validate the algorithm. Always reject tokens with alg: none in production.
Algorithm Confusion
If a server is configured to accept RS256 (asymmetric), an attacker might change the algorithm to HS256 (symmetric) and sign the token with the public key (which is often publicly available). If the server does not enforce the expected algorithm, it might accept the forged token. Always enforce the algorithm on the server side and do not let the token dictate which algorithm to use.
Token Sidejacking
If JWTs are stored in localStorage, they are vulnerable to cross-site scripting (XSS) attacks. A malicious script can read the token and send it to an attacker. Use HTTP-only cookies with the Secure, SameSite, and HttpOnly flags set.
Missing Expiration
Tokens without an exp claim are valid forever. If one is stolen, it grants permanent access. Always set an expiration time, and implement token revocation for critical scenarios (user logout, password change, compromised accounts).
Excessive Payload Size
Every claim you add increases the token size, and the token is sent with every request. Large tokens increase bandwidth usage and can even exceed header size limits on some servers. Keep your payload minimal.
JWT vs. Sessions: When to Use Which
JWTs are not always the right choice. Here is a quick comparison:
Choose JWTs when:
- You need stateless authentication at scale
- You are building a distributed system or microservice architecture
- You need cross-domain authentication (SSO)
- Your API serves mobile clients, SPAs, or third-party consumers
Choose sessions when:
- You need the ability to instantly revoke access (logout)
- You are building a traditional server-rendered application
- Your application is a monolith with a single server
- You need to store large amounts of session data
Many production systems use a hybrid approach: JWTs for short-lived access tokens combined with server-side refresh token storage for revocation capability.
Token Expiration and Refresh Flow
A well-designed JWT system uses two types of tokens:
Access tokens are short-lived (5 to 15 minutes) and contain the user's identity and permissions. They are sent with every API request.
Refresh tokens are long-lived (days or weeks) and stored securely on the server side. When an access token expires, the client uses the refresh token to obtain a new access token without requiring the user to enter credentials again.
Client Server
| |
|-- Login (credentials) ->|
| |-- Verify credentials
|<-- Access + Refresh ---|
| |
|-- API call + Access -->|
| |-- Verify token
|<-- Response ---|
| |
|-- Access expired -->|
|<-- 401 Unauthorized ---|
| |
|-- Refresh token -->|
| |-- Verify refresh token
|<-- New Access token ---|
This pattern gives you the performance benefits of stateless JWTs (no database lookup on every request) with the security benefit of being able to revoke refresh tokens when needed.
Wrapping Up
JWTs are a foundational technology for modern web authentication. They are compact, self-contained, and eliminate the need for server-side session storage. But they come with responsibilities — you need to choose the right algorithm, set proper expiration times, validate all claims, and never store sensitive data in the payload.
When you need to inspect or debug a token, use a JWT Decoder to instantly see its contents, verify its structure, and check its expiration status. Understanding what is inside your tokens is the first step toward building secure authentication systems.