Understanding JWT Tokens: A Complete Developer Guide

What is a JWT?

A JSON Web Token (JWT, pronounced "jot") is a compact, URL-safe token format used for securely transmitting information between parties. JWTs are widely used for authentication and authorization in web applications, mobile apps, and APIs. When you log into a website and stay logged in as you navigate between pages, there is a good chance a JWT is making that possible.

Unlike traditional session-based authentication where the server stores session data, JWTs are self-contained. They carry all the information needed to identify a user and their permissions, encoded directly in the token. This makes them ideal for distributed systems, microservices, and single-page applications.

The Three Parts of a JWT

Every JWT consists of three parts separated by dots: the header, the payload, and the signature. Each part is Base64URL-encoded, making the entire token safe to transmit in URLs, HTTP headers, and cookies.

Header

The header typically contains two pieces of information: the type of token (which is JWT) and the signing algorithm being used, such as HMAC SHA256 (HS256) or RSA (RS256). The algorithm tells the receiver how to verify the signature.

Payload

The payload contains the claims — statements about the user and additional metadata. There are three types of claims: registered claims (like "exp" for expiration time, "iat" for issued at, and "sub" for subject), public claims (defined in the IANA JSON Web Token Registry), and private claims (custom claims agreed upon between parties, like "role" or "userId").

Signature

The signature is created by taking the encoded header, the encoded payload, a secret key, and the algorithm specified in the header, then signing that data. The signature ensures that the token has not been altered. If anyone changes a single character in the header or payload, the signature will no longer match, and the token will be rejected.

How JWT Authentication Works

The typical JWT authentication flow works like this: a user sends their credentials (username and password) to the server. The server verifies the credentials, creates a JWT containing the user information and permissions, signs it with a secret key, and sends it back to the client. The client then includes this token in the Authorization header of every subsequent request.

When the server receives a request with a JWT, it verifies the signature to ensure the token is legitimate and has not been tampered with. It then checks the claims (like expiration time) and extracts the user information to process the request. No database lookup is needed to retrieve session data — everything is in the token itself.

Common JWT Claims Explained

Understanding the standard claims helps you design better token payloads. The "exp" claim sets when the token expires — after this time, the token should be rejected. The "iat" claim records when the token was issued. The "nbf" (not before) claim specifies the earliest time the token should be accepted. The "iss" claim identifies who issued the token, and "aud" specifies who it is intended for.

JWT Security Best Practices

JWTs are powerful but can be misused. Never store sensitive information like passwords in the payload — remember, the payload is encoded, not encrypted. Anyone with the token can decode and read it. Always set reasonable expiration times. Use HTTPS to prevent token interception. Store tokens securely on the client side, preferring httpOnly cookies over localStorage to prevent XSS attacks.

Choose strong signing algorithms. HS256 works well for simple applications where the same server issues and verifies tokens. RS256 is better for distributed systems where different services need to verify tokens without sharing a secret key.

Debugging JWTs

When working with JWT authentication, you will frequently need to inspect tokens to debug issues. Common problems include expired tokens, incorrect audience claims, missing required fields, and algorithm mismatches. A good JWT decoder lets you quickly see the header, payload, and expiration status without needing to write any code.

JWT vs. Session Tokens

The choice between JWTs and traditional session tokens depends on your architecture. Sessions are simpler and easier to invalidate (just delete the session from the server), but require server-side storage. JWTs are stateless and scale better across multiple servers, but cannot be easily revoked once issued (you need a token blacklist or short expiration times with refresh tokens).