JWT Explained: How JSON Web Tokens Work

JSON Web Tokens (JWTs) are everywhere in modern web authentication - if you've logged into a web app in the last several years, there's a good chance a JWT was involved somewhere in that flow. This guide breaks down what a JWT actually is, how to read one, and what to be careful of.

What a JWT is, in one sentence

A JWT is a compact, URL-safe string that encodes a set of claims (statements about a user or entity) along with a signature that proves those claims haven't been tampered with since they were issued.

The three parts of a JWT

A JWT is always three Base64URL-encoded segments separated by dots: header.payload.signature.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3F1cLdxx8sXwvvY

1. Header - identifies the signing algorithm and token type, e.g. algorithm HS256, type JWT.
2. Payload - the actual claims, e.g. subject and name. This is the part that carries identity and metadata.
3. Signature - computed by signing the header and payload with a secret (or private key), verifying the token hasn't been altered.

Common claim types

How JWTs are used in authentication

A typical flow: a user logs in, the server verifies their credentials and issues a signed JWT, and the client stores that token and sends it with subsequent requests (commonly in an Authorization: Bearer header). The server verifies the signature on each request instead of looking up a session in a database - which is the main appeal of JWTs: they're stateless and don't require a server-side session store.

Why JWTs deserve careful handling

Because a valid JWT is functionally equivalent to a temporary credential, a few things are worth keeping in mind:

• Never log a full JWT in plaintext - if it ends up in a shared log, anyone who sees it can use it until it expires.
• Keep expiration times short for access tokens, and use a separate refresh token flow for longer sessions.
• Verify the signature on every request server-side - never trust a JWT's claims without verifying it was actually signed by your server.
• Don't put highly sensitive data in the payload, since it's readable by anyone who has the token, not just your server.

JWTs showing up in logs

Because JWTs are passed in an Authorization header on almost every authenticated request, they're one of the most common things that accidentally end up in application and access logs - especially when a framework logs full request headers for debugging. If you're sharing a log that might contain a full JWT, mask it rather than leaving it in plaintext.

Common mistakes

• Assuming a JWT is encrypted because it's signed - signing proves integrity, not confidentiality.
• Storing JWTs in localStorage without considering XSS exposure - httpOnly cookies are a safer default for many web apps.
• Setting expiration times too long, which increases the window an exposed token remains usable.
• Logging the full Authorization header during debugging and forgetting to remove it before sharing.

Summary

A JWT packs identity claims and a verifiable signature into a compact string, made of a header, payload, and signature joined by dots. It's encoded, not encrypted, which means it should be treated like a bearer credential - handled carefully, kept out of logs in plaintext, and given a short expiration window.