JWT Decoders: Understanding JSON Web Tokens

JSON Web Tokens (JWTs) are the most common authentication mechanism in modern web applications. Understanding how they work — and how they can go wrong — is essential for every developer building or consuming APIs. This guide covers the fundamentals, security considerations, and tools for working with JWTs.

JWT Structure

A JWT consists of three parts separated by dots: header.payload.signature. The header specifies the algorithm (typically HS256 or RS256) and token type. The payload contains claims — key-value pairs with information like user ID, email, roles, and expiration time. The signature verifies that the token has not been tampered with.

Both the header and payload are Base64url-encoded JSON — they are NOT encrypted. Anyone who has the token can decode and read the header and payload. This is a critical point that many developers miss: JWTs are not a way to hide information. They are a way to verify that information has not been modified.

Common JWT Claims

Standard claims include: iss (issuer — who created the token), sub (subject — who the token represents), aud (audience — who the token is intended for), exp (expiration time — when the token becomes invalid), iat (issued at — when the token was created), and jti (JWT ID — a unique identifier for the token). Custom claims hold application-specific data like user roles, permissions, and preferences.

JWT Security Considerations

The most dangerous JWT vulnerability is the none algorithm attack. Some JWT libraries accept tokens with alg set to none, meaning no signature verification. Always validate the algorithm on the server and reject unexpected algorithms. Only accept the specific algorithm your application uses.

Another common vulnerability is using symmetric signing (HS256) with a weak secret. The secret should be at least 256 bits of cryptographic randomness, not a simple password or phrase. For production systems, prefer asymmetric signing (RS256 or ES256) where the private key stays on the server and the public key is distributed to services that need to verify tokens.

Token expiration is essential. Set short expiration times (15 minutes to 1 hour for access tokens) and use refresh tokens for long-lived sessions. Store refresh tokens securely (httpOnly, secure, sameSite cookies) and implement token rotation to limit the damage if a refresh token is compromised.

Our JWT Decoder

The AIDToolStack JWT Decoder lets you paste a JWT and instantly see the decoded header, payload, and signature information. It shows expiration status (valid, expired, or not yet valid), lists all claims with human-readable timestamps, and validates the token structure. Everything runs in your browser — your tokens never leave your machine, which is critical for production tokens that may contain sensitive information.

Other JWT Tools

jwt.io by Auth0 is the most well-known JWT debugger. It decodes tokens, displays claims, and can verify signatures if you provide the secret or public key. The downside is that your token is sent to their server for signature verification — do not paste production tokens with sensitive data. For offline verification, use our browser-based decoder or a command-line tool.

JWT in Practice

For Next.js applications, use a session library like NextAuth.js or Lucia that handles JWT creation, verification, and refresh automatically. For custom implementations, use the jose npm package (works in Node.js, Deno, Cloudflare Workers, and browsers) for standards-compliant JWT operations. Never implement JWT parsing or verification yourself — use a well-tested library that handles edge cases and known vulnerabilities.

When NOT to Use JWTs

JWTs are not always the right choice. For server-side rendered applications where the server makes all authenticated requests, traditional session cookies with server-side storage are simpler and more secure. JWTs cannot be revoked before expiration (without a server-side blocklist, which defeats the stateless benefit). If you need instant session revocation (for security incidents or user logout), session-based authentication is a better fit.