← Back to Blog

Understanding JWTs: How JSON Web Tokens Actually Work

What's inside a JWT, and why decoding isn't the same as verifying

By Wada Tsumi · Published June 18, 2026

What Is a JWT?

A JSON Web Token (JWT, pronounced "jot") is a compact, self-contained way to represent claims — statements about a user or entity — that can be verified and trusted because it's digitally signed. JWTs are the backbone of most modern authentication systems: log in once, receive a JWT, and send that token with every subsequent request instead of re-authenticating each time.

A JWT is not encrypted by default — it's signed, not sealed. Anyone who has the token can read its contents. What the signature guarantees is that the contents haven't been tampered with since the server issued it, not that they're secret.

The Three Parts of a JWT

A JWT is three Base64url-encoded segments joined by dots: header.payload.signature.

• Header — specifies the signing algorithm (e.g. HS256, RS256) and token type
• Payload — contains the claims: standard fields like sub (subject/user ID), iat (issued at), exp (expiration), plus any custom claims the application adds, like roles or permissions
• Signature — computed by signing the header and payload with a secret (HS256) or private key (RS256), so any modification to the header or payload invalidates the signature

Because the header and payload are just Base64url-encoded JSON — not encrypted — you can decode and read them without knowing the signing secret. Verifying the signature is a separate step that does require the secret or public key.

Reading a JWT: Decoding vs Verifying

These are two different operations that are easy to conflate:

• Decoding — reversing the Base64url encoding to read the header and payload as plain JSON. This requires no secret and reveals the claims, but proves nothing about authenticity.
• Verifying — recomputing the signature using the secret (HS256) or checking it against a public key (RS256) to confirm the token hasn't been altered and was actually issued by the expected authority.

A common mistake is decoding a JWT, seeing valid-looking claims, and assuming the token is legitimate. Without verification, anyone can craft a JWT with any payload they like — the signature is what separates "these claims look right" from "these claims are actually trustworthy."

Common JWT Claims

• iss — issuer, who created the token
• sub — subject, usually the user ID
• aud — audience, who the token is intended for
• exp — expiration time, as a Unix timestamp
• iat — issued-at time
• nbf — "not before," the token isn't valid until this time

Applications commonly add custom claims on top of these — a role, a tenant_id for multi-tenant systems, or a list of granted scopes.

HS256 vs RS256

The signing algorithm in the header determines how verification works:

• HS256 (HMAC with SHA-256) — a single shared secret both signs and verifies the token. Simple, but every service that needs to verify tokens must have the same secret, which increases exposure risk.
• RS256 (RSA with SHA-256) — an asymmetric key pair: the private key signs, and a public key verifies. Services that only need to verify tokens (not issue them) only need the public key, which is safe to distribute widely.

Most large-scale identity providers (Auth0, Okta, Firebase Auth) default to RS256 for exactly this reason — it lets many services verify tokens without ever holding the signing secret.

Why JWTs Expire — and What Happens When They Do

The exp claim exists because JWTs can't be revoked the way a server-side session can — once issued, a JWT remains technically valid until it expires, even if the user's access should have been revoked. Short expiration times (minutes, not days) combined with a refresh token mechanism is the standard mitigation: the short-lived JWT limits the damage window if a token is somehow leaked, while the refresh token (usually stored more securely) issues new JWTs as needed.

Debugging JWTs in Practice

When an API call fails with an auth error, decoding the JWT you're sending is often the fastest way to diagnose it. Common issues a quick decode reveals:

• The token has already expired (exp is in the past)
• The token was issued for the wrong audience (aud doesn't match the API you're calling)
• A required custom claim (like a role or scope) is missing or misspelled
• The token is from the wrong environment — a staging token accidentally sent to production, or vice versa

Quick FAQ

Can I read a JWT's contents without the secret key? Yes — decoding the header and payload requires no secret, since they're only Base64url-encoded, not encrypted.

Is it safe to paste a JWT into an online decoder? Only if the tool processes it client-side. A JWT often contains user IDs, roles, and other claims you may not want logged on someone else's server, even though it isn't a password.

Why does my decoded JWT look valid but the API still rejects it? Decoding only shows you the claims — it doesn't confirm the signature is valid. An expired, tampered, or wrong-audience token can still decode into readable JSON while failing verification.

Decode JWTs Instantly

Use the DataBench JWT Decoder to inspect the header and payload of any JSON Web Token, check its expiration, and optionally verify HS256 signatures — entirely in your browser, with nothing sent to a server.