JSON Web Tokens (JWT): A Complete Guide

JSON Web Tokens (JWT) have become the de facto standard for securing APIs and handling authentication in single-page applications (SPAs). But what exactly is that long string of characters starting with eyJ?

Anatomy of a JWT

A JWT is composed of three parts, separated by dots (.):

• Header: Contains metadata about the token type and cryptographic algorithm.
• Payload: Contains the "claims" (user data like ID, role, expiration).
• Signature: A cryptographic signature to verify the token hasn't been tampered with.

1. The Header

{
  "alg": "HS256",
  "typ": "JWT"
}

2. The Payload

{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022
}

Decoding vs. Verifying

It's crucial to understand that decoding a JWT is different from verifying it.

Since the header and payload are just Base64Url encoded, anyone can decode them and read the contents. This is why you should never put sensitive secrets (like passwords) inside a JWT payload.

Verifying, however, requires the secret key. The server uses the secret key to recalculate the signature and ensure it matches the one in the token.

Common Use Cases

• Authentication: The most common scenario. Once the user is logged in, each subsequent request will include the JWT, allowing the user to access routes, services, and resources.
• Information Exchange: JWTs are a good way of securely transmitting information between parties. Because they can be signed, you can be sure the senders are who they say they are.

Standard JWT Claims

JWTs can contain any claims you want, but there are standard registered claims (defined in the JWT specification):

JWT Security Best Practices

• Use HTTPS: Always transmit JWTs over HTTPS to prevent man-in-the-middle attacks
• Set short expiration times: Use refresh tokens for long-lived sessions
• Validate all claims: Don't just check the signature - verify exp, nbf, aud, and iss
• Store securely: In browsers, use httpOnly cookies instead of localStorage for sensitive tokens
• Use strong secrets: For HS256, use a long, random secret. For RS256, use proper key management
• Never put secrets in the payload: Remember, the payload is easily decodable

Common JWT Vulnerabilities

Algorithm Confusion Attack

If a server accepts tokens with "alg": "none" or doesn't verify the algorithm, attackers can create tokens without a valid signature. Always verify the algorithm matches what you expect.

Weak Secrets

Using weak or predictable secrets makes it easy for attackers to forge tokens. Use cryptographically secure random secrets that are at least 256 bits long.

Token Replay

If a token is intercepted, it can be reused until it expires. Implement token revocation mechanisms or use short expiration times with refresh tokens.

JWT vs. Session Tokens

JWTs are stateless, meaning the server doesn't need to store session data. This makes them ideal for:

• Microservices architectures where services don't share session storage
• Single Page Applications (SPAs) that make API calls to multiple services
• Mobile applications that need to authenticate with backend APIs

However, traditional session tokens (stored server-side) are better when you need:

• Immediate revocation (JWTs can't be revoked until they expire)
• Strict security requirements (sessions can be invalidated instantly)
• Large payloads (JWTs should be kept small due to size constraints)

Inspect Your Tokens

Debugging authentication issues often requires inspecting the claims inside your token. Is the exp (expiration) timestamp correct? Does the user have the admin role? Is the iss (issuer) what you expect?

Use our JWT Decoder to instantly parse and inspect your tokens client-side, without sending them to any server. This tool is perfect for:

• Debugging authentication issues in development
• Verifying token claims before making API calls
• Understanding JWT structure and contents
• Checking token expiration times
• Learning how JWTs work through hands-on exploration

All decoding happens in your browser - your tokens never leave your device, ensuring complete privacy and security.