What is a JWT, and when should you not use one?
A JSON Web Token is a signed, self-contained token carrying claims — typically who the user is and when the token expires — which a server can verify without a database lookup. That property is its entire value and the source of all its problems.
The structure. Three base64url-encoded parts separated by dots: a header naming the algorithm, a payload of claims, and a signature. The signature proves the token was issued by someone holding the key and has not been altered.
The most important misconception: a JWT is signed, not encrypted. The payload is readable by anyone holding the token — base64 is encoding, not protection. Never put anything confidential in it.
When it genuinely fits:
Stateless verification across services, where a service can validate a token locally without calling an auth service.
Short-lived access tokens in OAuth flows.
Cross-domain scenarios where cookies are awkward.
When you should not use one:
As a session replacement in an ordinary web application. This is the most common mistake. Server-side sessions with an opaque cookie are simpler, revocable immediately, and smaller — and the scaling problem JWTs solve is one most applications do not have.
When you need immediate revocation. A signed token is valid until it expires; logging out, banning a user or changing permissions does not invalidate it. The usual fix — checking a revocation list — reintroduces the database lookup the JWT existed to avoid, at which point you have a complicated session.
When the payload grows, since it travels on every request.
The implementation traps:
The alg: none vulnerability, where a library accepts an unsigned token. Always specify the expected algorithm rather than trusting the header.
Algorithm confusion, where an RSA public key is used as an HMAC secret.
Storing tokens in localStorage, which is readable by XSS — HttpOnly cookies are safer.
Missing expiry, audience or issuer validation.
Use a maintained library, and do not implement this yourself.