JWT Token Debugging Guide: Fix Errors Fast

What is a JWT?

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and 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 ubiquitous in modern web development, serving as the backbone for Stateless Authentication.

The Anatomy of a JWT

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

xxxxx.yyyyy.zzzzz
Header.Payload.Signature

1. Header

The header typically consists of two parts: the type of the token (JWT) and the signing algorithm being used, such as HMAC SHA256 or RSA.

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

2. Payload (Claims)

The payload contains the claims. Claims are statements about an entity (typically, the user) and additional data.

• Registered claims: Predefined claims like iss (issuer), exp (expiration time), sub (subject), aud (audience).
• Public claims: Custom claims defined by those using JWTs (e.g., role, email).
• Private claims: Custom claims created to share information between parties that agree on using them.

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

Warning: The payload is Base64Url encoded, not encrypted. Anyone who has the token can decode it and read the data. Never put secrets like passwords in the payload.

3. Signature

To create the signature part you have to take the encoded header, the encoded payload, a secret, the algorithm specified in the header, and sign that.

HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  secret)

The signature is used to verify the message wasn't changed along the way, and, in the case of tokens signed with a private key, it can also verify that the sender of the JWT is who it says it is.

Common Debugging Scenarios

1. "Invalid Signature" Error

This is the most common error. It means the signature generated by your server doesn't match the signature in the token.

• Cause: Wrong secret key, wrong public key, or the token content was tampered with.
• Fix: Ensure your verification server uses the exact same secret used to sign the token.

2. Token Expired (exp)

JWTs are valid only until the timestamp in the exp claim.

• Debug: Decode the token and check the exp value. It is a Unix timestamp (seconds since epoch).
• Fix: If exp is in the past, you must issue a new token (refresh token flow).

3. Clock Skew

If your server's clock is slightly different from the auth server's clock, valid tokens might be rejected as "not yet valid" (nbf) or "expired".

• Fix: Most JWT libraries allow for a "leeway" or "clock tolerance" configuration (e.g., allow 30 seconds difference).

4. Audience (aud) Mismatch

The aud claim specifies who the token is intended for. If your API expects aud: "my-api" but the token has aud: "other-service", validation will fail.

Security Best Practices

1. Do Not Store Sensitive Data

As mentioned, JWTs are easily decoded. Do not store:

• User passwords
• API secrets
• Personal Private Information (PII) if not encrypted

2. Always Verify Signature

Never trust a JWT without verifying its signature. An attacker could forge a token with admin: true if you only decode it without verification.

3. Use Strong Algorithms

Prefer RS256 (RSA Signature with SHA-256) or ES256 (ECDSA) over HS256 (HMAC). Asymmetric algorithms allow you to share the public key for verification without risking the private signing key.

4. The alg: none Attack

Historically, some libraries allowed tokens with {"alg": "none"}, meaning no signature verification. Attackers could strip the signature and bypass security. Modern libraries disable this by default, but always ensure your library rejects none.

How to Debug Safely

When debugging production tokens, you need to be careful not to paste them into untrusted online tools that might log them.

Use Client-Side Decoders: Tools like our JWT Decoder run entirely in your browser. The token never leaves your device, ensuring that your production secrets stay safe while you inspect headers and payloads.

Conclusion

JWTs are powerful but require careful handling. By understanding their structure—Header, Payload, Signature—and using secure debugging tools, you can troubleshoot authentication issues effectively without compromising security.