If you have built or consumed a modern REST API, you have almost certainly encountered a JWT. JSON Web Tokens appear in Authorization headers, URL parameters, and local storage across virtually every authentication system built in the last decade. They look like random strings — eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c — but they are actually structured, verifiable data with a precise format that makes stateless authentication possible.
The Three-Part Structure of a JWT
A JWT consists of three Base64URL-encoded parts separated by dots: header.payload.signature. Each part is independently readable — Base64URL is an encoding, not encryption. The header identifies the token type and signing algorithm. The payload contains the claims (the data you care about). The signature proves the header and payload have not been tampered with.
The header is a JSON object like {"alg": "HS256", "typ": "JWT"}. The algorithm field specifies how the signature was created. Common algorithms include HS256 (HMAC-SHA256, symmetric — uses one shared secret), RS256 (RSA-SHA256, asymmetric — uses a private key to sign and public key to verify), and ES256 (ECDSA-SHA256, asymmetric — smaller signature than RSA).
The payload contains claims — statements about the subject and metadata. Standard registered claims include sub (subject, typically a user ID), iss (issuer), aud (audience), exp (expiration timestamp), iat (issued at timestamp), and nbf (not before timestamp). Custom claims like {"role": "admin", "email": "user@example.com"} can be added freely. Because the payload is only Base64URL-encoded (not encrypted), never put sensitive data like passwords, SSNs, or credit card numbers in a JWT payload.
How Signature Verification Works
The signature is computed by taking the Base64URL-encoded header, a dot, the Base64URL-encoded payload, and signing that string with the algorithm and key specified in the header. For HS256: HMAC-SHA256(base64url(header) + "." + base64url(payload), secret). The result is Base64URL-encoded to form the signature.
When a server receives a JWT, it re-computes the signature using the same algorithm and key, then compares it to the signature in the token. If they match, the token has not been modified. This is the key property: without the secret key, an attacker cannot forge a valid signature for a modified payload. The server trusts the claims in the payload only after signature verification passes.
The exp claim is critical: always validate token expiration. A JWT with a valid signature but an expired exp timestamp should be rejected. Libraries handle this automatically when you use them correctly, but manual JWT implementations often forget expiration checks. An unexpiring JWT is a permanent credential — if it is ever leaked, it cannot be revoked without invalidating all tokens.
Stateless Authentication and Its Trade-offs
Traditional session-based authentication stores session state in a server-side database: the browser holds a session ID cookie, and the server looks up the session ID on every request. JWTs invert this: all the information needed to authenticate the user is embedded in the token itself, so the server needs no database lookup to verify identity.
Statelessness enables horizontal scaling. Any server that has the signing key can verify any JWT — no session database, no sticky sessions, no distributed session synchronization. This is why JWTs became dominant in microservice architectures and serverless functions where each request may be handled by a different instance.
The fundamental trade-off is revocation. With session-based auth, you can invalidate a session instantly by deleting it from the database. With JWTs, there is no standard revocation mechanism — a token is valid until it expires. Immediate revocation requires a token blacklist (a database lookup that defeats the stateless benefit) or very short expiration times. Most systems use short-lived access tokens (15 minutes) paired with longer-lived refresh tokens stored in a database.
Common JWT Security Mistakes
The "none" algorithm attack: early JWT libraries accepted {"alg": "none"} in the header, meaning no signature was required. An attacker could modify the payload freely and claim no signature was needed. Always verify the algorithm explicitly in your code — never accept whatever algorithm the token claims.
Storing JWTs in localStorage makes them accessible to JavaScript, exposing them to XSS attacks. A single XSS vulnerability anywhere on your site lets an attacker steal every JWT in localStorage. Storing JWTs in HttpOnly cookies makes them inaccessible to JavaScript (though CSRF protection is then needed). There is no perfect storage option — the choice is a trade-off between XSS and CSRF risk based on your threat model.
Using weak secrets for HS256 allows offline brute-force attacks. An attacker who intercepts a JWT can attempt to find the signing secret offline by testing candidate secrets against the signature. HS256 secrets should be cryptographically random and at least 256 bits (32 bytes) long. For public-facing APIs, RS256 or ES256 with asymmetric keys is the safer choice because the private key never leaves the server.
JWTs are a powerful and well-suited tool for stateless authentication in distributed systems, but they come with security properties that require deliberate implementation choices. Understanding the three-part structure, how signature verification works, and the trade-offs around revocation and storage makes you a more informed consumer and implementer. A JWT decoder lets you instantly inspect any token — examining claims, checking expiration, and verifying the algorithm — without writing a single line of code.