JWT Debugging Guide: Header, Claims, Expiration & Signature Troubleshooting

JSON Web Tokens (JWT) specified in RFC 7519 are the ubiquitous standard for stateless authentication in modern REST and GraphQL APIs. However, troubleshooting token rejections is one of the most frequent developer headaches.

Understanding the 3 JWT Segments

A compact JWT is a string of three Base64URL-encoded parts separated by periods (.):

[HEADER].[PAYLOAD].[SIGNATURE]

1. Header: Identifies the token type and cryptographic algorithm (e.g. HS256, RS256).
2. Payload: Contains claims such as sub (subject), iss (issuer), exp (expiration timestamp), and iat (issued-at timestamp).
3. Signature: Cryptographic hash verifying that the sender is authentic and the message was not tampered with.

Top 4 Reasons JWT Verification Fails in Production

1. Expiration (exp) Unit Confusion (Seconds vs. Milliseconds)

The most common mistake is providing the expiration timestamp in JavaScript milliseconds rather than Unix seconds:

// ❌ WRONG: Date.now() returns 13-digit milliseconds
const badExp = Date.now() + 3600000; 

// ✅ CORRECT: JWT RFC 7519 requires 10-digit Unix Epoch seconds
const correctExp = Math.floor(Date.now() / 1000) + 3600;

2. Clock Skew Between Microservices

If your authentication microservice and resource server have slightly unsynchronized system clocks, a newly minted token may be rejected with TokenNotYetValid or prematurely expired. Always configure a 30 to 60-second leeway in verification libraries.

3. Symmetric (HS256) vs Asymmetric (RS256) Key Mixup

In asymmetric systems (RS256), the issuing server signs with a Private Key, while consumer APIs verify using the public key certificate. Passing public keys into symmetric verifiers will fail verification immediately.

4. Safe Client-Side Inspection

When an API returns a 401 Unauthorized, developers need to quickly inspect token claims. Use DevKitLab's JWT Decoder to decode headers, payloads, and timestamps without leaking your bearer token to third-party endpoints.