JSON Web Tokens, or JWTs, have become the dominant mechanism for stateless authentication in modern web applications. From Silicon Valley startups to European fintech platforms, JWTs enable secure, scalable authentication without the overhead of server-side session storage. But with great power comes great responsibility — JWTs are easy to implement incorrectly, and security mistakes can expose your application to devastating attacks. For developers building applications that serve US and EU users, understanding JWTs is essential not only for security but also for compliance with data protection regulations like GDPR and CCPA. In this comprehensive guide, we cover everything from JWT structure to security best practices and regulatory considerations.
What Is a JWT?
A JSON Web Token is an open standard (RFC 7519) that defines a compact, self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs are commonly used for authentication and information exchange in web applications and APIs.
The key characteristic of a JWT is that it is self-contained. Unlike a session ID, which is just a reference to data stored on the server, a JWT contains all the information needed to identify and authenticate the user. This includes the user's ID, their roles or permissions, the token's expiration time, and any other claims the application needs. Because the token is signed, the server can verify its integrity without needing to look it up in a database.
This stateless nature makes JWTs ideal for distributed systems and microservice architectures. A user authenticates once and receives a JWT. That token can then be presented to any service that trusts the signing key, without each service needing to communicate with a central session store. This is why JWTs are the standard authentication mechanism in modern API-driven applications.
JWT Structure Explained
A JWT consists of three parts separated by dots: the header, the payload, and the signature. The structure looks like this: header.payload.signature. Each part is Base64url-encoded, making the token safe to transmit in URLs and HTTP headers.
Header
The header typically contains two fields: the token type ("JWT") and the signing algorithm being used (such as "HS256" for HMAC SHA-256 or "RS256" for RSA SHA-256). The header is Base64url-encoded to form the first part of the token.
Payload
The payload contains the claims — statements about an entity (typically, the user) and additional metadata. There are three types of claims: registered claims (like "iss" for issuer, "exp" for expiration time, "sub" for subject), public claims (defined by the application), and private claims (custom claims agreed upon by the parties). The payload is Base64url-encoded to form the second part of the token.
It is critical to understand that the payload is not encrypted. It is merely encoded, which means anyone who has the token can decode and read its contents. Never put sensitive information like passwords, credit card numbers, or personal data in a JWT payload unless you are using JWE (JSON Web Encryption) to encrypt the token.
Signature
The signature is created by taking the encoded header, the encoded payload, a secret key (for HMAC algorithms) or a private key (for RSA algorithms), and signing them using the algorithm specified in the header. The signature ensures that the token has not been tampered with — if any part of the header or payload is changed, the signature will not match.
How JWT Authentication Works
The typical JWT authentication flow works as follows. First, the user submits their credentials (username and password) to an authentication endpoint. The server verifies the credentials and, if valid, generates a JWT containing the user's ID, roles, and an expiration time. The JWT is signed with the server's secret key or private key and returned to the client.
The client stores the JWT (in localStorage, sessionStorage, or an HTTP-only cookie) and includes it in the Authorization header of subsequent requests as a "Bearer" token. When the server receives a request with a JWT, it verifies the signature using the secret or public key, checks the expiration time, and extracts the user information from the payload. If the token is valid, the request is processed; if not, the server returns a 401 Unauthorized response.
For long-lived sessions, a refresh token mechanism is often used. The initial authentication returns both a short-lived access token (the JWT) and a longer-lived refresh token. When the access token expires, the client uses the refresh token to obtain a new access token without requiring the user to log in again. This balances security (short access token lifetimes) with user experience (no frequent re-authentication).
Security Best Practices
JWT security is a deep topic, but several best practices are universally recommended. First, always use HTTPS. JWTs transmitted over HTTP can be intercepted and read by anyone on the network. HTTPS encrypts the entire communication channel, protecting the token from interception. This is non-negotiable for any production application.
Second, choose the right signing algorithm. HMAC algorithms (HS256, HS384, HS512) use a single shared secret, which is simpler but requires all services that verify the token to have access to the secret. RSA algorithms (RS256, RS384, RS512) use asymmetric keys — a private key for signing and a public key for verification. This is more secure for distributed systems because only the authentication service needs the private key, while all other services can verify tokens with the public key.
Third, never accept tokens with the "alg": "none" header. This is a known JWT vulnerability where an attacker sets the algorithm to "none," which tells the server to skip signature verification. Always explicitly whitelist the algorithms your application accepts and reject any token with an unexpected algorithm.
Fourth, keep access tokens short-lived. A 15-minute or 1-hour expiration limits the window of opportunity if a token is stolen. Combined with refresh tokens, this provides a good balance of security and user experience. Always set the "exp" claim and enforce it on the server.
Fifth, do not store sensitive data in the payload. Remember that the payload is encoded, not encrypted. Anyone with the token can read its contents. Store only the user ID and roles — not personal data, financial information, or secrets. If you need to include sensitive data, use JWE (JSON Web Encryption) to encrypt the token.
GDPR and CCPA Considerations
For applications serving EU users, GDPR compliance affects how JWTs are used. The payload of a JWT may contain personal data — user IDs, email addresses, role information. Under GDPR, personal data must be processed lawfully, fairly, and transparently, and it must be minimized — only the data necessary for the purpose should be included.
This means you should avoid putting unnecessary personal data in JWT payloads. A user ID is typically sufficient for authentication. Including email addresses, full names, or other personal data in the token increases the scope of personal data processing and may require additional GDPR documentation. If the token is stored in a cookie, the ePrivacy Directive (the "Cookie Directive") may also apply, requiring user consent for non-essential cookies.
For US applications subject to CCPA, similar principles apply. The California Consumer Privacy Act gives consumers the right to know what personal information is collected about them and to request its deletion. If JWTs contain personal information, this must be disclosed in your privacy policy, and deletion requests must be honored — which may require invalidating existing tokens.
In both jurisdictions, using a client-side tool to decode and inspect JWTs — like the JWT Decoder — helps developers understand exactly what personal data their tokens contain. This is valuable for privacy audits and for ensuring that token payloads are minimized.
How to Decode and Inspect JWTs
Decoding a JWT is the process of Base64url-decoding the header and payload to read their contents. This does not verify the signature — it simply reveals the information stored in the token. Decoding is useful for debugging authentication issues, verifying that the correct claims are present, and checking expiration times.
The Automarkly JWT Decoder lets you paste a JWT and instantly see the decoded header and payload as formatted JSON. It also displays the signature portion and identifies the signing algorithm. The tool runs entirely in your browser, which is important for security — your tokens never leave your device, and there is no risk of them being logged on a server.
When inspecting JWTs, check the following: the "alg" field in the header (ensure it is an expected algorithm), the "exp" claim (ensure the token has not expired), the "iss" claim (ensure it matches your expected issuer), and the "sub" claim (ensure it contains the expected user identifier). Any unexpected values may indicate a misconfiguration or a security issue.
Common Pitfalls to Avoid
One of the most common JWT pitfalls is storing tokens in localStorage and assuming they are secure. localStorage is accessible to any JavaScript running on the page, which means a single XSS vulnerability can allow an attacker to steal all tokens. For security-critical applications, consider storing tokens in HTTP-only cookies with the SameSite attribute set to "Strict" or "Lax" to protect against both XSS and CSRF attacks.
Another pitfall is not validating the algorithm. Some JWT libraries allow the client to specify the algorithm, which can lead to algorithm confusion attacks. For example, if a server expects RS256 (asymmetric) but accepts HS256 (symmetric), an attacker could sign a token with the public key using HS256, and the server would verify it using the public key as the HMAC secret. Always explicitly specify the expected algorithm on the server side.
A third pitfall is not handling token expiration properly. If the server does not check the "exp" claim, expired tokens remain valid indefinitely. Always enforce expiration and return a 401 response for expired tokens. On the client side, handle 401 responses gracefully by redirecting to the login page or using a refresh token to obtain a new access token.
Finally, do not put too much data in the token. JWTs are transmitted with every request, so large tokens increase bandwidth and latency. Keep the payload minimal — user ID, roles, and expiration are typically sufficient. If you need more user data, fetch it from the server after authentication rather than embedding it in the token.
JWTs are a powerful authentication mechanism, but they require careful implementation to be secure. By understanding the structure, following security best practices, and considering regulatory requirements, you can build authentication systems that serve US and EU users safely and compliantly. To inspect your tokens, try the free JWT Decoder — it runs entirely in your browser with zero data uploads.