What Is a JWT and How Does It Work?

JSON Web Tokens (JWTs) are everywhere in modern authentication, yet they're widely misunderstood — sometimes in ways that cause real security holes. This guide explains what a JWT actually is, what its signature does (and doesn't) guarantee, and how to use them safely.

What is a JWT?

A JWT is a compact, URL-safe way to represent a set of claims — statements like "this user's ID is 42" or "this token expires at 3pm" — that one party can give to another. Its defining feature is that it's signed, so the receiver can verify it hasn't been altered and was issued by someone who holds the signing key.

The three parts

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

• Header — declares the token type and signing algorithm, e.g. {"alg":"HS256","typ":"JWT"}.
• Payload — the claims, e.g. {"sub":"42","exp":1730000000}.
• Signature — computed over the header and payload using the signing key.

Crucially, the header and payload are only encoded, not encrypted. Anyone who has the token can read them. Paste a token into a JWT decoder and you'll see the JSON instantly — which is exactly why you must never put secrets in a JWT.

How signing works

The signature is what makes a JWT trustworthy. For the common HS256 algorithm, the signature is an HMAC-SHA256 of header.payload using a shared secret. When the server receives the token back, it recomputes that HMAC with the same secret and checks it matches. If a single character of the payload was changed, the signature won't match and the token is rejected.

The signature proves integrity and authenticity (the token wasn't tampered with and came from someone with the key). It does not provide confidentiality — that's the most common misconception.

HS256 vs RS256

The two families you'll meet most often:

• HS256 (symmetric) — one shared secret signs and verifies. Simple, fast, but everyone who can verify can also forge, so the secret must stay on trusted servers.
• RS256 (asymmetric) — a private key signs, a public key verifies. The verifier can't create tokens, which is ideal when many independent services need to validate tokens issued by one authority.

Typical login flow

1. The user logs in with a username and password.
2. The server verifies the credentials and issues a signed JWT containing the user ID and an expiry.
3. The client sends that JWT on each request (usually in an Authorization: Bearer header).
4. The server verifies the signature and expiry on every request — no database lookup needed to trust the claims.

Common security mistakes

• Putting secrets in the payload. It's readable. Store only non-sensitive identifiers.
• Not verifying the signature. Decoding is not validating. Always verify before trusting any claim.
• Accepting alg: none. Some libraries historically accepted unsigned tokens — reject anything whose algorithm isn't what you expect.
• Weak HS256 secrets. A short secret can be brute-forced. Use a long random one from our API key generator.
• Ignoring expiry. Always set and check exp; short-lived tokens limit the blast radius of a leak.

See it in action

The best way to understand JWTs is to build and break one. Create a signed token with our JWT generator, then decode and verify it with the JWT decoder — change one character of the payload and watch the signature check fail.