JWTs for Stateless API Authentication

WHY IT EXISTS Traditional session-based authentication requires a server-side store to track logged-in users. In distributed or horizontally-scaled systems, this shared session store becomes a performance bottleneck and a single point of failure. Stateless authentication with JWTs was created to solve this by embedding user data directly in a verifiable token, removing the need for a centralized session database.

THE MENTAL MODEL Think of a JWT as a tamper-proof ID card or a festival wristband. The server issues it upon successful login. The user then presents this card with every subsequent request. Any service can verify the card's authenticity by checking its signature, trusting the information on it (like user ID and permissions) without needing to look up the user in a central database. The card also has an expiration date, after which it's invalid.

HOW IT WORKS A JWT consists of three parts separated by dots: a header, a payload, and a signature. The header defines the signing algorithm. The payload contains claims—statements about the user, like their ID and roles. The signature is a cryptographic hash of the header and payload, created using a secret key known only to the server. When a client sends a JWT, the server re-computes the signature to verify the token hasn't been altered. Importantly, the payload is only Base64 encoded, not encrypted, so it should never contain sensitive data.

WHEN TO USE IT Use JWTs to secure APIs, especially in microservice architectures where different services need to independently verify a user's identity. The standard pattern is to use two tokens: a short-lived access token (e.g., 15 minutes) for API requests and a long-lived refresh token (e.g., 7 days) to get new access tokens without forcing a re-login.

WHEN NOT TO USE IT JWTs are difficult to revoke immediately. Once issued, a token is valid until it expires. If you need to instantly log out a user (e.g., after a password change), you must implement a server-side blocklist, which reintroduces state. For simple, monolithic apps, traditional server-side sessions can be easier to manage.

ONE CANONICAL EXAMPLE In an Express.js app, a user logs in. The server validates their credentials and generates a short-lived access token and a long-lived refresh token. The access token is sent in the response body for the client to include in future Authorization: Bearer <token> headers. The refresh token is sent as an HttpOnly, Secure cookie. When the access token expires, the client's browser automatically sends the refresh token cookie to a /refresh endpoint to get a new access token.