Understanding JWT
Three parts, joined by dots.
A signed claim about who you are, in three Base64 sections.
The three parts.
Every JSON Web Token is three Base64-URL-encoded JSON blobs joined with dots. The first is the header — what algorithm signed this. The second is the payload — the actual claims (who you are, when you logged in, when this token expires). The third is the signature — a cryptographic stamp proving the first two haven't been tampered with.
header.payload.signature
The header.
A small JSON object that announces the token's metadata — almost always just two fields: the algorithm (alg) used to sign it (HS256, RS256, ES256, …) and the type (typ: "JWT"). Decoded, it usually reads like {"alg":"HS256","typ":"JWT"}.
The payload.
The claims. Some are reserved by the spec — sub is the subject (usually the user id), iss is the issuer, iat is "issued at" (a Unix timestamp), exp is "expires at." Anything else is application- specific: roles, permissions, the user's email. Treat the payload as readable by anyone — it's just Base64. Don't put secrets in it.
The signature.
The signature is the only part that needs the secret key. The server takes the header and payload, runs them through the chosen algorithm with its private key, and gets a fixed-length binary blob — Base64-URL-encoded, this becomes the third section. To verify a token, you re-run the same calculation with your copy of the key and check the signatures match. If they don't, the token is forged.
What JWT does not do.
JWT signs claims. It does not encrypt them. The payload is plain JSON behind a Base64 wrapper — anyone holding a token can read its contents. If you need confidentiality, use JWE (the encrypted cousin) or transport the JWT over TLS only and avoid putting sensitive data in the claims at all.
The "alg: none" attack.
The original JWT spec allowed alg: none, meaning "no signature." Any server that trusted the header's algorithm declaration could be fooled by a token with no real signature at all. Modern libraries default to rejecting none; if you write JWT code, never accept the algorithm from the header — pin it on the server.
When to use JWTs (and when not).
JWTs shine for stateless authentication across services that all share a key — log in once, carry the token to every microservice. They're a poor choice for session tokens that might need to be revoked: once issued, a JWT is valid until it expires, and short of a deny-list you can't take it back. For long-lived sessions on a single server, a server-side session and a random-bytes cookie remain the safer pattern.
Read next