JWT Decoder

The Day a JWT Bug Cost Us 3 Hours of Sleep

It was 11 PM on a Friday when the support tickets started flooding in. "Can't login." "Session expired immediately." "Getting kicked out constantly." Our authentication was completely broken, and we had no idea why.

Two hours of frantic debugging later, I copied a JWT from a failed request, pasted it into a decoder, and there it was: the exp claim was set to a date in 1970. Someone had passed seconds instead of milliseconds to the timestamp function. The token was expiring 50 years ago.

That's when I truly understood why every developer needs a JWT decoder in their toolkit. Not just for debugging emergencies, but for everyday API development.

What Is a JWT, Really?

A JSON Web Token (JWT, pronounced "jot") is a compact, URL-safe way to represent claims between two parties. In plain English: it's a secure way to pass information that can be verified and trusted.

The concept originated from the need to handle authentication in distributed systems. Traditional sessions required server-side storage—every request needed to hit a database or cache to verify the session. JWTs flip this: they contain everything needed for verification within the token itself.

JWTs have three parts, separated by dots:

1. Header: The algorithm used and token type (usually "JWT")
2. Payload: The actual data (claims about the user)
3. Signature: The verification hash that proves the token wasn't tampered with

Here's the key insight that trips up many developers: the header and payload are only Base64-encoded, not encrypted. Anyone can decode them. The signature is what prevents tampering—if you change even one character in the payload, the signature won't match.

How JWT Authentication Actually Works

Let me walk through the complete flow, because understanding this is essential for debugging:

1. Login Request

User sends credentials (email/password) to your auth server. The server validates against the database, probably checking a hashed password.

2. Token Generation

If credentials are valid, the server creates a JWT. It builds a payload with claims like:

{
  "sub": "user-123",
  "email": "user@example.com",
  "role": "admin",
  "iat": 1703980800,
  "exp": 1704067200
}

Then it signs this with the secret key (HS256) or private key (RS256).

3. Token Delivery

The JWT is sent back to the client. Best practice: use an httpOnly cookie for the refresh token, and keep the access token in memory (not localStorage—that's vulnerable to XSS).

4. Authenticated Requests

Client includes the JWT in the Authorization header: Bearer eyJhbGc.... Every request carries this token.

5. Server Verification

The receiving server verifies the signature (using the secret or public key), checks that the token isn't expired, and reads the claims. No database lookup needed—everything is in the token.

JWT Algorithms: HS256 vs RS256

This is where security architecture decisions happen. The algorithm you choose has real implications:

HS256 (HMAC with SHA-256)

• Type: Symmetric—same secret for signing and verifying
• Pros: Faster, simpler, smaller keys
• Cons: Every service that verifies needs the secret
• Best for: Single-service applications, internal APIs

RS256 (RSA Signature with SHA-256)

• Type: Asymmetric—private key signs, public key verifies
• Pros: Only auth server needs the private key; public key can be shared freely
• Cons: Slower, larger keys, more complex setup
• Best for: Microservices, third-party integrations, OAuth

Common JWT Security Vulnerabilities

Over the years, I've seen (and sometimes caused) various JWT-related security issues. Here are the ones that keep showing up:

The "alg: none" Attack

Some JWT libraries accept tokens with "alg": "none", meaning "this token has no signature, trust it anyway." Attackers could forge tokens by setting this algorithm. Modern libraries reject this, but always verify yours does.

Algorithm Confusion

If your server expects RS256 but accepts HS256, an attacker could use your public key (which is, well, public) as the HS256 secret. Some libraries allowed this switch. Always explicitly specify which algorithm your server accepts.

Weak Secrets

For HS256, a weak secret can be brute-forced. Use at least 256 bits of cryptographic randomness. "secret123" is not a secret—it's the first thing attackers try.

Long Expiration Times

JWTs can't be revoked (easily). A token valid for a year means a stolen token is valid for a year. Keep access tokens short-lived (15 minutes to 1 hour) and use refresh tokens for longer sessions.

Debugging JWTs: A Systematic Approach

When authentication fails, here's my debugging checklist:

1. Decode the Token

First, just see what's in it. Use this tool—paste the token, check the payload. Does it contain what you expect?

2. Check Expiration

Is exp in the future? Is it reasonable? Watch for timezone issues (all JWT timestamps should be UTC) and unit confusion (seconds vs milliseconds).

3. Verify the Algorithm

Does the header's alg match what your server expects? Mismatches cause signature verification failures.

4. Check Audience and Issuer

If your server validates aud and iss, do the values match your configuration? This catches cross-environment token issues.

5. Look for Missing Claims

Does your server require certain claims (sub, roles, etc.)? Are they present? Null or missing values cause subtle authorization bugs.

6. Check Token Size

JWTs with many claims get large. Some servers have header size limits. If your token is over 4KB, you might hit issues with proxies or CDNs.

JWT vs Sessions: An Honest Comparison

JWTs aren't always the right choice. Here's when each approach works best:

Use JWTs for: APIs consumed by mobile apps, microservices architectures, cross-domain authentication, OAuth/OpenID Connect.

Use sessions for: Traditional web apps, situations requiring instant revocation (admin account compromise), simple single-server deployments.

How This Tool Works

When you paste a JWT, the tool:

1. Splits the token into three parts at the dots
2. Base64URL-decodes the header and payload (handling the URL-safe alphabet)
3. Parses the JSON and pretty-prints it with syntax highlighting
4. Converts Unix timestamps to human-readable dates in your timezone
5. Calculates whether the token is expired based on the exp claim

Everything happens in your browser using JavaScript. Your tokens are never sent to any server. This is critical—production JWTs often contain sensitive claims and should never be pasted into tools that might log them.

Final Thoughts

JWTs are everywhere in modern web development. They're in your API authentication. They're in OAuth flows. They're in the ID tokens from social logins. Understanding them—how they work, what they contain, what can go wrong—is essential for any developer working with web services.

The decoder above is simple by design. It shows you what's in the token, nothing more. But that's often all you need. When authentication breaks at midnight, being able to instantly see what's actually in the token—what the expiration is, what claims are present, which algorithm is used—that's the difference between a quick fix and an all-night debugging session.

Keep this bookmarked. You'll use it more than you expect.