JSON Web Tokens (JWTs): Stateless API Passports

WHY IT EXISTS: Traditional server-side sessions require storing user data, which becomes a bottleneck and a scaling challenge in distributed systems. JWTs were created as a compact, URL-safe way to represent user information, or 'claims', that can be securely transferred between parties. This enables stateless authentication, where the server doesn't need to maintain session state.

THE MENTAL MODEL: A JWT is a tamper-proof digital passport. When a user logs in, the server issues them a JWT containing claims like their user ID and permissions. For every subsequent request to a protected resource, the user presents this passport. The server verifies the digital signature to ensure the passport is authentic and hasn't been altered. If valid, the server trusts the claims inside without needing a database lookup.

HOW IT WORKS: A JWT consists of three parts separated by dots: Header, Payload, and Signature. The Header specifies the signing algorithm. The Payload is a JSON object containing the claims (e.g., user ID, roles, expiration date). The Header and Payload are Base64Url encoded, making them readable but not encrypted. The Signature is created by hashing the encoded header, payload, and a secret key known only to the server. This signature proves the token's integrity.

WHEN TO USE IT: JWTs are ideal for stateless authentication in APIs, especially in microservices architectures. Since any service with the secret key can verify the token, it removes the need for a centralized session store. They are also commonly used by Single Page Applications (SPAs) to manage user sessions with a backend.

WHEN NOT TO USE IT: Avoid JWTs if you need the ability to immediately revoke a user's session. Since JWTs are stateless and self-contained, they are valid until they expire. Forcibly logging a user out requires maintaining a server-side blocklist, which defeats the purpose of being stateless. Also, do not store sensitive information in the payload, as it is only encoded, not encrypted.

ONE CANONICAL EXAMPLE: A user submits their login credentials. The server validates them and generates a JWT containing {"userId": 123, "role": "user"}. The server signs it and sends it to the client. The client then includes this token in the Authorization: Bearer <jwt> header for all future API requests. On receiving a request, the API server verifies the token's signature using its secret key before granting access to the requested resource.