JWT Guide

JWTs are simple to decode and easy to misuse if you skip verification

A JSON Web Token carries claims in a compact string, but the important part is not decoding it. The important part is verifying who issued it and whether it should still be trusted.

JWT anatomy

A token has three Base64url-encoded sections separated by dots.

header.payload.signature

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkphbmUgRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Header

Declares the token type and the signing algorithm.

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

Payload

Contains claims about the user, client, or session.

{"sub":"123","exp":1700000000}

Signature

Protects header and payload from tampering when verification is implemented correctly.

HMAC-SHA256(...)

Registered claims

Claim	Name	Meaning
`iss`	Issuer	Which system created the token
`sub`	Subject	Who the token is about
`aud`	Audience	Which service should accept it
`exp`	Expiration	Reject after this Unix timestamp
`nbf`	Not Before	Reject before this Unix timestamp
`iat`	Issued At	When it was minted
`jti`	JWT ID	Unique identifier for replay controls

Common signing algorithms

HS256 / HS384 / HS512

Symmetric HMAC algorithms. The same shared secret signs and verifies the token.

RS256 / RS384 / RS512

Asymmetric RSA algorithms. A private key signs and a public key verifies.

ES256 / ES384 / ES512

Asymmetric elliptic-curve signatures with smaller keys and signatures than RSA.

alg: none

Unsigned tokens. Do not allow these in production verification paths.

How verification works

Split the token on . to extract header, payload, and signature.
Decode the header and compare alg against the algorithm you expect. Do not trust the header alone.
Recompute the signature over header.payload using the correct secret or public key flow.
Compare the provided signature and the recomputed one.
Validate claims like expiration, audience, issuer, and not-before rules.

Security guidance

Decoding is not trust

A JWT decoder shows you the contents, but it does not prove the token is authentic. Trust begins only after signature and claim verification succeed.

Pin the expected algorithm and reject surprises.
Keep token lifetimes short and use refresh flows for longer sessions.
Never put secrets in the payload because payloads are readable after decoding.
Use strong random secrets for HMAC and proper key management for asymmetric signing.
Always transmit tokens over HTTPS.