JWT tokens explained: how to decode them safely (2026)

What is a JWT token?

A decoded JWT is not a trusted JWT.

That distinction is the most important thing to understand about JSON Web Tokens, and it is the one most often missed by developers first working with them. Decoding a JWT is trivial. Anyone can do it, including attackers. The payload is base64-encoded, not encrypted, and base64 is reversible without any key. Decoding tells you what the token says. Verification tells you whether to believe it.

JWTs are widely used because they solve a real problem: stateless authentication at scale. When a server issues a signed token, any other server with the right key can verify it without calling back to the original server or hitting a shared session store. This scales well, works across services, and reduces infrastructure complexity. Those advantages are real.

The tradeoff is that JWT security depends entirely on correct implementation. The signature prevents tampering -- but only if you verify it. The expiration prevents indefinite use -- but only if you check it. The algorithm field specifies how the signature was made -- but only if you validate it against an allowlist rather than accepting whatever the token claims. This guide covers how JWTs actually work, how to decode and inspect them safely, and where implementations go wrong.

The three parts are base64url-encoded and joined with dots:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyXzEyMyIsInJvbGUiOiJhZG1pbiIsImV4cCI6MTc1MDAwMDAwMH0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

The first . separates the header from the payload. The second . separates the payload from the signature.

What is a JWT token?

“Self-contained” is the key characteristic. Unlike a session ID (which is a random string that maps to server-stored session data), a JWT carries all the information the server needs to authenticate the request. The user's ID, their roles, when the token was issued, when it expires, and any other custom data the application needs -- all of this is in the token itself, signed so it cannot be modified without detection.

Authentication vs authorization: Authentication means proving who you are. JWTs are issued after successful authentication (login with username and password, OAuth flow, etc.). Authorization means proving what you are allowed to do. The JWT payload typically carries roles or permissions that downstream services use to determine what the bearer is allowed to access.

The stateless property is the main advantage. A traditional session requires every request to hit a session store (Redis, database) to look up the session. A JWT-based API can verify identity on any server that has the signing key, without centralized session storage. This works well for microservices, distributed systems, and third-party API access.

The tradeoff: JWT revocation is harder. You cannot “log out” a JWT the way you log out a session. Once issued, a JWT is valid until it expires, unless you implement a token blocklist (which reintroduces server-side storage). The payload of a JWT should be treated as public information unless encrypted -- do not put sensitive data in the payload.

How JWT authentication works

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT structure explained

HEADER.PAYLOAD.SIGNATURE

The critical distinction: base64 encoding is not encryption. It is a reversible encoding format that converts binary data to URL-safe text. Anyone who has the JWT token can decode the header and payload into plain text in seconds. This is by design -- JWTs are meant to be inspectable.

What the signature does provide: tamper detection. If any byte in the header or payload changes after signing, the signature will not match. A server that correctly verifies the signature can trust that the claims in the payload have not been modified since the token was issued.

Real JWT example

A realistic JWT for an API service:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyXzEyMyIsInJvbGUiOiJhZG1pbiIsImlzcyI6ImF1dGgubXlhcHAuY29tIiwiYXVkIjoiYXBpLm15YXBwLmNvbSIsImV4cCI6MTc1MDAwMDAwMCwiaWF0IjoxNzQ5OTk2NDAwLCJqdGkiOiJhYmMxMjMifQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Decoded header:

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

Decoded payload:

{
  "sub": "user_123",
  "role": "admin",
  "iss": "auth.myapp.com",
  "aud": "api.myapp.com",
  "exp": 1750000000,
  "iat": 1749996400,
  "jti": "abc123"
}

The signature:

The signature is not meaningful JSON. It is the result of:

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

JWT decode vs JWT verify

If you decode a JWT and use the sub claim to identify the user without verifying the signature, an attacker can create their own JWT with any sub value they choose, sign it with a random key, and send it to your server. If your server only decodes and does not verify, it will accept that token and treat the request as coming from any user the attacker specifies.

The algorithm confusion attack exploits this: if a server accepts whatever algorithm the token header claims, an attacker can change "alg": "HS256" to "alg": "none" and remove the signature entirely. Always verify against an explicit algorithm allowlist, never against what the token claims.

How to decode a JWT safely

Manual decoding (for inspection only):

// JavaScript -- decode only, not verify
const [headerB64, payloadB64, signature] = token.split('.');
const header = JSON.parse(atob(headerB64.replace(/-/g, '+').replace(/_/g, '/')));
const payload = JSON.parse(atob(payloadB64.replace(/-/g, '+').replace(/_/g, '/')));
// Do NOT trust header or payload without signature verification

Proper verification (for production use):

// Node.js with jsonwebtoken library
const jwt = require('jsonwebtoken');

try {
  const decoded = jwt.verify(token, process.env.JWT_SECRET, {
    algorithms: ['HS256'],  // Explicit allowlist, never accept 'none'
    issuer: 'auth.myapp.com',
    audience: 'api.myapp.com'
  });
  // decoded contains verified claims
  console.log(decoded.sub); // Safe to use
} catch (err) {
  // Token invalid, expired, or tampered
  return res.status(401).json({ error: 'Unauthorized' });
}

# Python with PyJWT library
import jwt

try:
    payload = jwt.decode(
        token,
        secret_key,
        algorithms=['HS256'],  # Explicit allowlist
        issuer='auth.myapp.com',
        audience='api.myapp.com'
    )
    # payload contains verified claims
except jwt.ExpiredSignatureError:
    # Token has expired
    pass
except jwt.InvalidTokenError:
    # Token is invalid for any reason
    pass

Common JWT claims explained

The aud claim is a security boundary. If your API server's identifier is api.myapp.com and a token has aud: mobile.myapp.com, your server should reject it even if the signature is valid. Cross-audience token use is a known attack vector.

Custom claims (like role in the example above) are not standardized. Agree on a consistent naming convention within your team and document what each custom claim means.

JWT expiration and refresh tokens

Access token:  15-60 min lifetime, sent with every request
Refresh token: 7-30 day lifetime, sent only to token endpoint
Rotation:      New refresh token on every use; old one invalidated

Common JWT security mistakes

JWT attacks developers should know

The RS256 to HS256 attack: some JWT libraries accept whatever algorithm the token header specifies. If a server uses RS256 and a library does not enforce an allowlist, an attacker can create a token with "alg": "HS256"and sign it with the server's public key. If the library then uses the public key as the HMAC secret, the signature verifies successfully. The fix in every library is the same: specify the allowed algorithms explicitly when calling verify.

JWT decoder example

Developers routinely need to inspect JWT contents while debugging: what claims are in a token, whether it has expired, what user ID it contains, what permissions it grants. Decoding a JWT manually requires splitting on ., base64url-decoding each segment, and pretty-printing the JSON.

For debugging a production issue, the workflow is:

When to use JWT vs sessions

Neither JWTs nor sessions are universally better. Pick based on your architecture and requirements.

JWT vs session cookies

JWT best practices

One-minute JWT security audit

Quick answers for AI search

Optimized for ChatGPT, Gemini, Perplexity, Claude, and Google AI Overviews.

Frequently asked questions

Tools used in this guide

Related guides