You've seen them — long strings of three dot-separated chunks pasted into Slack, debug logs, and API playgrounds everywhere. JWT tokens are the backbone of modern authentication, but most developers treat them as opaque blobs. Let's open one up.

What a JWT actually is

A JWT (JSON Web Token) is three Base64URL-encoded segments joined by dots:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
.eyJzdWIiOiJ1c2VyXzEyMyIsIm5hbWUiOiJKYW5lIERvZSIsInJvbGUiOiJhZG1pbiIsImlhdCI6MTcxNjIzMDAwMCwiZXhwIjoxNzE2MjMzNjAwfQ
.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

The three parts are: header, payload, signature.

The header

Decode the first segment with atob() (or any Base64 decoder) and you get:

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

alg tells the server which algorithm was used to sign the token. Common values:

• HS256 — HMAC-SHA256 (symmetric, shared secret)
• RS256 — RSA-SHA256 (asymmetric, public/private key pair)
• ES256 — ECDSA-SHA256 (asymmetric, elliptic curve)

none is also technically valid — and historically caused major vulnerabilities when servers accepted it.

The payload (the interesting part)

The payload contains claims — statements about the user and the token itself:

{
  "sub": "user_123",
  "name": "Jane Doe",
  "role": "admin",
  "iat": 1716230000,
  "exp": 1716233600
}

Standard registered claims:

Custom claims like role, email, permissions are application-specific and perfectly valid.

Important: the payload is Base64URL-encoded, not encrypted. Anyone with the token can read these claims. Never put passwords, credit card numbers, or other secrets in the payload.

The signature

The signature is computed as:

HMAC-SHA256(
  base64url(header) + "." + base64url(payload),
  secret_key
)

The server uses this to verify the token hasn't been tampered with. If you flip one character in the payload, the signature won't match and the token is rejected.

This is what makes JWTs useful — the server doesn't need a database lookup for every request. It just validates the signature mathematically.

Reading a JWT without a library

In JavaScript:

function decodeJwt(token) {
  const [header, payload] = token.split('.');
  const decode = (str) => JSON.parse(atob(str.replace(/-/g, '+').replace(/_/g, '/')));
  return {
    header: decode(header),
    payload: decode(payload)
  };
}

The - → + and _ → / replacements convert Base64URL back to standard Base64, which atob() accepts.

In Python:

import base64, json

def decode_jwt(token):
    parts = token.split('.')
    # Pad to multiple of 4
    payload = parts[1] + '==' 
    return json.loads(base64.urlsafe_b64decode(payload))

The expiry trap

exp is a Unix timestamp (seconds since 1970-01-01 UTC). Check it like this:

const { exp } = decodeJwt(token).payload;
const isExpired = Date.now() / 1000 > exp;

A common mistake: trusting an expired token because you forgot to check exp. JWT libraries like jsonwebtoken (Node.js) and PyJWT (Python) check expiry automatically when you call their verify functions — but raw decoding does not.

The algorithm confusion attack

Never accept alg: none on your server. This was a real vulnerability in early JWT libraries — an attacker could strip the signature and set alg to none, and some servers would accept the forged token as valid.

Similarly, if your server uses asymmetric RS256 (public/private key), an attacker might try sending a token with alg: HS256 and sign it using your public key as the HMAC secret. Always specify the expected algorithm explicitly:

jwt.verify(token, publicKey, { algorithms: ['RS256'] });

Quick decode in the browser

If you're debugging an auth issue and need to quickly inspect what claims a token contains, paste it into this JWT decoder — it decodes header and payload client-side with no server upload, highlights expiry status, and labels all standard claims.

Stateless auth and its tradeoffs

The appeal of JWTs for authentication is statelessness — the server encodes everything it needs into the token and signs it, so there's no session lookup on every request. This scales across multiple servers without shared session storage.

The tradeoff: you can't revoke a JWT before it expires without maintaining a blocklist (which reintroduces state). The standard mitigations:

• Short expiry (15 minutes) + refresh tokens (longer-lived, stored server-side)
• Revocation list for critical events (logout, password change, account ban)
• Token rotation — issue a new access token each time a refresh token is used

JWS vs JWE

What you almost always see is JWS — JSON Web Signature. The payload is readable; the signature prevents tampering.

JWE (JSON Web Encryption) encrypts the payload entirely and produces a 5-part token. Use JWE when the JWT itself must carry sensitive data that shouldn't be readable without a key — most auth tokens don't need this.

JWT tokens are simpler than they look once you see the three-part structure. The magic is all in the signature — a tiny cryptographic proof that the claims haven't changed since the server issued the token.