Understanding JWT Tokens: A Developer's Guide

JSON Web Tokens (JWTs) are everywhere in modern web development — they power authentication in REST APIs, OAuth flows, SSO systems, and serverless platforms. Yet their opaque, base64-encoded appearance makes them a black box for many developers. This guide opens that box.

The Three-Part Structure

A JWT is three Base64URL-encoded strings joined by dots: Header.Payload.Signature. Each part serves a distinct purpose.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFsaWNlIiwiaWF0IjoxNzQzMDAwMDAwLCJleHAiOjE3NDMwODY0MDB9
.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Header

The header is a JSON object that declares the token type ("JWT") and the signing algorithm. Common algorithms: HS256 (HMAC-SHA256, symmetric), RS256 (RSA-SHA256, asymmetric), and ES256 (ECDSA, asymmetric). The choice has major security implications.

Payload (Claims)

The payload contains claims — statements about the entity (usually the user) plus metadata. Standard registered claims include: sub (subject/user ID), iat (issued at timestamp), exp (expiry timestamp), iss (issuer), and aud (audience). Custom claims carry application-specific data like roles or permissions.

Signature

The signature is computed by signing the encoded header and payload with a secret (HS256) or private key (RS256/ES256). Recipients verify the signature with the shared secret or public key, proving the token was not tampered with in transit.

What "Signed" Means (and Does Not Mean)

Signing guarantees integrity (the token has not been modified since it was issued) and authenticity (the token was created by a party holding the correct secret or private key). If you need confidentiality in addition, use JWE (JSON Web Encryption).

Reading Expiry & Timestamps

The iat and exp claims are Unix timestamps (seconds since epoch). A system clock skew of even a few minutes can invalidate a token that appears fresh. When debugging an "invalid token" error, always check the exp claim first.

// Decode exp manually (no library)
const [, payload] = token.split(".");
const decoded = JSON.parse(atob(payload.replace(/-/g,"+").replace(/_/g,"/")));
console.log("Expires:", new Date(decoded.exp * 1000).toLocaleString());
console.log("Expired:", Date.now() > decoded.exp * 1000);

Common Security Pitfalls

• 01"alg: none" attack — never accept tokens where the algorithm is "none". Always validate the algorithm server-side.
• 02HS256 vs RS256 confusion — an RS256 server accepting HS256 tokens can be tricked into verifying the public key as the HMAC secret.
• 03Storing tokens in localStorage — XSS can exfiltrate localStorage. Prefer httpOnly cookies for sensitive tokens.
• 04Missing expiry validation — always validate exp server-side. Never trust the client to expire a token.
• 05Overly broad audience (aud) — tokens accepted by any service can be replayed across services.

Using the DevWallah JWT Decoder

Paste any JWT into the DevWallah JWT Decoder and it instantly renders the decoded header and payload as formatted JSON. It also displays human-readable timestamps for iat, exp, and nbf claims, and highlights whether the token is expired. All decoding happens in-browser — your tokens are never sent to any server.