JWT Tokens Decoded: How They Work and How to Read Them

If you've worked with any modern authentication system — OAuth 2.0, Auth0, Firebase Auth, or a custom API with Bearer tokens — you've used JWTs. They look like random noise, but there's a precise structure inside. Here's how to read them.

The Three Parts

A JWT is a string of three Base64url-encoded segments separated by dots: header.payload.signature. If you paste one into a decoder, you get three distinct sections.

Header

The header is a small JSON object declaring the token type and the signing algorithm:

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

The algorithm field (alg) tells the recipient how the signature was created. Common values are HS256 (HMAC-SHA256, symmetric — one shared secret), RS256 (RSA-SHA256, asymmetric — public/private key pair), and ES256 (ECDSA, used where compact signatures matter).

Payload

The payload contains the actual claims — statements about the user or session. There are registered claim names with standard meanings:

• sub — subject (usually a user ID)
• iss — issuer (who created the token)
• aud — audience (who the token is intended for)
• exp — expiry time as a Unix timestamp
• iat — issued at time
• nbf — not valid before

You can also add any custom claims your application needs, like role, email, or plan.

Signature

The signature is computed from the encoded header and payload plus a secret key. It lets the recipient verify that the token wasn't tampered with. If someone modifies the payload (say, changes their role from "user" to "admin"), the signature won't match and the server rejects the token.

The Critical Security Point

The payload is not encrypted — it's just Base64url encoded, which anyone can decode without a key. Never put sensitive information in a JWT payload (passwords, credit card numbers, PII that shouldn't be exposed). The signature only ensures integrity, not confidentiality.

If you need the contents to be secret, you want a JWE (JSON Web Encryption) rather than a plain JWT.

Why JWTs Are Stateless

The main practical advantage of JWTs is that the server doesn't need to look up the token in a database to validate it. It just verifies the signature with its key. This makes them useful for distributed systems and microservices where storing session state centrally is inconvenient.

The tradeoff: you can't revoke a JWT before it expires unless you maintain a blocklist (which partially defeats the stateless advantage). Short expiry times plus refresh tokens is the standard pattern to manage this.

Debugging JWTs

When debugging auth issues, decoding the JWT is often the fastest first step. Check the exp claim — is the token expired? Check aud — is the audience matching what your server expects? Check iss — is it from the issuer you trust?

Use our JWT Decoder to inspect any token — paste it in and see all three sections decoded, including the expiry time rendered as a human date.