JWT Tokens Explained: How to Decode, Verify, and Debug JSON Web Tokens

What Is a JWT Token?

A JSON Web Token (JWT, pronounced "jot") is a compact, URL-safe token format used to securely transmit information between two parties. Defined by RFC 7519, JWTs are the backbone of modern authentication and authorisation flows — from single-page apps calling REST APIs to microservices verifying each other's identity.

Unlike opaque session tokens that require a server-side lookup, JWTs are self-contained: everything needed to validate the token and extract user information is baked right into the token itself. This makes them stateless, scalable, and ideal for distributed systems.

JWT Structure: Header, Payload, and Signature

Every JWT consists of three Base64URL-encoded parts separated by dots:

header.payload.signature

// Example:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

1. Header

The header is a JSON object that describes the token type and the signing algorithm. It is Base64URL-encoded to form the first segment.

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

2. Payload (Claims)

The payload carries the claims — statements about the user and additional metadata. Claims come in three flavours:

• Registered claims: Standardised fields like iss, exp,sub, and iat.
• Public claims: Custom fields registered in the IANA JSON Web Token Claims registry to avoid collisions.
• Private claims: Application-specific fields agreed upon between parties (e.g.,role, orgId).

{
  "sub": "user_4821",
  "name": "Jane Smith",
  "role": "admin",
  "iss": "https://auth.example.com",
  "iat": 1716163200,
  "exp": 1716166800
}

3. Signature

The signature is created by taking the encoded header and payload, concatenating them with a dot, and signing the result using the algorithm specified in the header.

// HMAC-SHA256 example
HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secret
)

Signing Algorithms: HS256 vs RS256

The signing algorithm is arguably the most critical decision when working with JWTs. The two most common algorithms are:

With HS256, the same secret is used to sign and verify the token. This is simple but means every service that needs to verify tokens must have access to the secret. With RS256, only the auth server holds the private key; any service can verify tokens using the freely distributed public key.

Common JWT Claims Explained

The registered claims defined in RFC 7519 provide a shared vocabulary. Here are the most important ones:

The Verification Process

When your server receives a JWT, it must verify the token before trusting its contents. Here is the standard verification flow:

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

try {
  const decoded = jwt.verify(token, publicKey, {
    algorithms: ['RS256'],       // explicit allowlist
    issuer: 'https://auth.example.com',
    audience: 'my-api',
  });
  console.log('User ID:', decoded.sub);
} catch (err) {
  console.error('Token verification failed:', err.message);
}

Common Security Mistakes

JWTs are secure by design, but misusing them can introduce serious vulnerabilities. Watch out for these common pitfalls:

• Storing tokens in localStorage: This exposes tokens to cross-site scripting (XSS) attacks. Prefer HttpOnly, Secure, SameSite cookies instead.
• Not validating the algorithm: An attacker can change the header to"alg": "none" or switch from RS256 to HS256 (using the public key as the HMAC secret). Always enforce the algorithm server-side.
• Overly long expiration times: Tokens valid for days or weeks increase the window of compromise. Use short-lived access tokens (5–15 minutes) paired with refresh tokens.
• Sensitive data in the payload: Remember, the payload is only encoded, not encrypted. Anyone can decode it. Never put passwords, credit card numbers, or secrets in the payload.
• Ignoring token revocation: JWTs are stateless, making revocation non-trivial. Use short expiration times, token blacklists, or the jti claim for revocation scenarios.

Debugging JWT Issues

When a JWT-based flow breaks, here's a systematic approach to tracking down the problem:

1. Decode the token: Paste it into a JWT decoder to inspect the header and payload. Verify the claims look correct.
2. Check expiration: Convert the exp claim to a human-readable date. Clock skew between servers is a common cause of premature expiration.
3. Verify the issuer and audience: Mismatched iss or aud values cause silent rejections in many libraries.
4. Confirm the signing key: For HS256, ensure the secret matches exactly (including encoding). For RS256, verify you're using the correct public key or JWKS endpoint.
5. Inspect the HTTP headers: Confirm the token is being sent asAuthorization: Bearer <token> and not accidentally truncated.

Conclusion

JWTs are a powerful, standardised way to handle authentication and authorisation in modern applications. Their self-contained nature makes them perfect for stateless architectures, but that same power demands careful implementation. By understanding the structure, choosing the right algorithm, validating claims rigorously, and avoiding common security pitfalls, you can build JWT-based systems that are both secure and scalable.

When in doubt, lean on well-maintained libraries for signing and verification — don't roll your own crypto. And always keep a JWT debugger handy during development; it will save you hours of frustration.