JWT Explained: Structure, Claims, and How to Decode One

If you've worked with a modern web API, you've met JWTs — those long strings of gibberish with two dots in them that show up in login responses and Authorization headers. They look opaque, but they're surprisingly readable once you know the structure. This guide explains what a JSON Web Token is, what's inside it, how the signature works, and the security mistakes to avoid.

What a JWT is for

A JSON Web Token (JWT) is a compact, self-contained way to carry a set of claims — statements like “this is user 42 and they signed in at 10:05.” Its main use is authentication: after you log in, a server issues a JWT, your app sends it back with each request, and the server trusts it instead of looking you up in a session store every time. Because the token carries the information itself, it's called stateless.

The three parts

Every JWT is three Base64URL-encoded sections joined by dots: header.payload.signature.

eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI0MiJ9.3x9kQ...
└──── header ────┘ └── payload ──┘ └ signature ┘

1. Header

Metadata about the token — the signing algorithm (alg, e.g. HS256) and type (typ: JWT). Decoded, it's just small JSON:

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

2. Payload

The claims — the actual data. Some names are standardized (called registered claims):

• sub — subject, usually the user ID.
• iss — issuer, who created the token.
• aud — audience, who it's meant for.
• exp — expiration time (a Unix timestamp).
• iat — issued-at time (a Unix timestamp).

Those exp and iat values are seconds since 1970 — if you need to read them as real dates, a timestamp converter turns them into human-readable times.

3. Signature

The signature is what makes the token trustworthy. The issuer takes the header and payload, and using a secret key, produces a cryptographic signature. Anyone with the key can verify that the header and payload haven't been altered — change a single character in the payload and the signature no longer matches.

The most important thing to understand

A JWT is signed, not encrypted. The header and payload are only Base64URL-encoded, which means anyone can decode and read them — no key required. The signature prevents tampering, not reading.

The practical consequence: never put secrets in a JWT payload. No passwords, no credit card numbers, no private data — assume the payload is public. You can confirm this for yourself by pasting any token into our JWT decoder, which reads the header and claims instantly, entirely in your browser (the token never leaves your device). Under the hood it's just Base64 decoding — the decoder simply saves you the steps.

Verifying vs. decoding

These are two different actions, and mixing them up is a real security bug. Decoding reads the payload — anyone can do it and it proves nothing. Verifying checks the signature with the key and confirms the token is genuine and unaltered. A server must verify every token before trusting it; decoding alone is not authentication.

Common pitfalls

• Trusting an unverified token — always check the signature server-side before acting on the claims.
• Ignoring expiry — honor exp; an expired token should be rejected.
• Storing sensitive data in the payload— it's readable by anyone.
• The alg: none trap— some libraries once accepted tokens claiming “no signature.” Reject them, and pin the expected algorithm.

Understand those, and JWTs go from intimidating strings to a simple, transparent format: readable claims, protected by a signature you must verify before you trust.