Developer Tools

JWT Decoder: The Complete Guide

A JSON Web Token (JWT) is a compact, URL-safe string that carries a signed JSON payload between a client and a server. When you log in to almost any modern API, the response includes a JWT that your app then sends on every subsequent request. This guide covers how to decode one, what to look for, and — importantly — the difference between decoding and verifying.

What a JWT looks like

A JWT is three base64url-encoded strings joined by dots: *header.payload.signature*. Each part has a specific job.

• The header describes the signing algorithm and (optionally) the key ID.
• The payload carries the actual claims — who the user is, when the token expires, what they can access.
• The signature proves the header and payload have not been changed since the issuer signed them.

The header and payload are only base64 — anyone can decode them. That's the point. The signature is what makes the token trustworthy.

What the decoder does (and doesn't)

The decoder splits the token on its dots, base64-decodes the header and payload, and pretty-prints the resulting JSON. It does not verify the signature — that requires the issuer's public key or shared secret, and it must happen server-side. Anyone can decode a JWT; only your server should trust the contents.

Step-by-step debugging with a JWT

1. Paste the token. Drop the *Bearer* prefix if present.

2. Read the header. Confirm the algorithm (*alg*). If it says *none*, throw the token away — the *none* algorithm is a well-known attack surface.

3. Read the payload. Check the standard claims:

• iss (issuer) — who minted the token.
• sub (subject) — usually the user ID.
• aud (audience) — who the token is meant for.
• exp (expiry) — Unix timestamp. Convert to a date and compare with now.
• iat (issued at) — when the token was minted.
• nbf (not before) — earliest valid time.

Custom claims (roles, scopes, tenant IDs) appear alongside these.

4. Compare against the failing request. \"Invalid audience\"? Check *aud*. \"Expired\"? Check *exp*. \"Wrong tenant\"? Check the custom claim.

Common debugging scenarios

• \"Token expired.\" *exp* is in the past. Refresh the token from the auth server.
• \"Invalid audience.\" *aud* doesn't match what the resource server expects. Fix the audience in your auth config.
• \"Signature verification failed.\" Almost always a key mismatch. The token was signed with a key different from what the verifier is checking against.
• Missing custom claim. Decode, confirm the claim is absent, then fix the rule in your auth provider that should have added it.

Security warnings

• Never trust the payload without verifying the signature. Decoding is trivial. A malicious client can produce any payload it wants; the signature is the only thing that says the server actually issued it.
• Never put secrets in a JWT payload. The payload is base64, not encrypted. Anyone with the token can read every claim.
• **Never accept tokens signed with *alg: none*.** Configure your JWT library to reject that algorithm explicitly.
• Prefer short-lived access tokens (minutes to hours) paired with a longer-lived refresh token. If a token leaks, the damage is bounded.

What about JWE?

Standard JWTs are signed but not encrypted. If you need the payload to be secret from the client, use JWE (JSON Web Encryption). For most authentication flows, though, signing is enough — the payload is not sensitive, it's just claims like \"user 5821 is allowed to access this API until 4pm.\"

Privacy

The decoder runs entirely in your browser using the *atob* API. The token you paste is never sent to a server. Even so, get in the habit of using development-environment tokens for debugging — any tool that touches a real production token is one accidental log line away from being a security incident.

Wrapping up

JWTs are one of the most useful and most misunderstood building blocks in modern web development. Decode them freely to debug; verify them rigorously to trust them. The decoder here is safe to use as often as you like — but always remember that reading a JWT is not the same as trusting it.

7 min read