A JSON Web Token (JWT) is how most modern APIs and login systems pass identity and permission data between a client and a server without a database lookup on every request. If you've ever opened your browser's dev tools and seen a long string starting with "eyJ" in a request header, that's a JWT.
The three parts
Every JWT is three Base64URL-encoded segments joined by dots: header.payload.signature.
- Header — states the token type and the signing algorithm, commonly HS256 (shared secret) or RS256 (public/private key pair).
- Payload — the actual claims: user ID, roles, expiry, and any custom data the issuer chose to include. This is readable by anyone; it is not encrypted.
- Signature — proves the header and payload haven't been altered since signing. Recomputing it requires the issuer's secret key, which is why only the server can validate a token, not just read it.
Decoding isn't a security flaw
This trips up a lot of people the first time they see it: anyone can decode a JWT and read its payload, and that's expected, not a bug. What keeps a JWT trustworthy is the signature — change even one character of the payload and the signature no longer matches, so a server verifying the token will reject it. Decoding shows you the claims; it does not let you forge a valid token, because you'd need the issuer's secret key to produce a matching signature.
Common claims you'll see
- sub — Subject, the user or entity the token identifies.
- iss — Issuer, which server or auth system generated the token.
- aud — Audience, the intended recipient of the token.
- exp — Expiration, a Unix timestamp after which the token is no longer valid.
- iat — Issued At, a Unix timestamp of when the token was created.
Using a decoder to debug auth issues
Most "why is this user logged out" or "why does the API return 401" bugs come down to one of a few things visible directly in the decoded payload: the exp claim has already passed, the aud doesn't match what the API expects, or a role/permission claim is missing entirely. Pasting the token into a decoder turns a guessing game into a five-second check.
What decoding does not tell you
A decoder cannot verify the signature — that requires the secret or public key, which never leaves the server. If you need to confirm a token is genuinely valid (not just well-formed), that check has to happen server-side, using a JWT library and the actual signing key.