Decoding and Debugging JWTs: A Developer's Checklist

JWT authentication issues are frustrating to debug because the symptoms are vague — mysterious 401s, intermittent failures, users unexpectedly logged out — and error messages from libraries aren't always specific. This checklist gives you a systematic approach.

Connect on LinkedIn →

Step 1: Decode the Token and Read the Claims

Before anything else, decode the token and check its actual contents. At least half of JWT debugging issues are resolved here — the token simply contains wrong or missing claims because of a bug in token generation code.

• What algorithm does the header specify (alg)?
• Has the token expired (exp in the past)?
• Is the issuer (iss) what the server expects?
• Is the audience (aud) correct for this service?
• Are custom claims (roles, permissions) present and correct?

Expiry Issues

Clock skew between servers

If auth and API servers have clocks differing by more than a few seconds, just-issued tokens may appear expired. Most JWT libraries have configurable clock skew tolerance (typically 60 seconds). Ensure all servers sync via NTP.

Detecting expiry manually

const payload = JSON.parse(atob(token.split('.')[1]));
const expiry = new Date(payload.exp * 1000);
console.log(`Expires: ${expiry.toLocaleString()}`);
console.log(`Expired: ${expiry < new Date()}`);

Signature Verification Failures

A signature failure means the token was tampered with, was signed with a different key, or the verifier is using the wrong key. For HS256, the same secret must sign and verify. For RS256, services use the public key — ensure it's current after key rotation. Many auth servers include a kid (key ID) in the header to identify which key to use from the JWKS endpoint.

Always Specify the Algorithm Explicitly

// BAD — accepts any algorithm (vulnerable to algorithm confusion)
jwt.verify(token, secret);

// GOOD — specify allowed algorithms
jwt.verify(token, secret, { algorithms: ['HS256'] });

Claim Validation Failures

• Audience mismatch: verify aud matches your service — a token for your mobile app shouldn't be accepted by your admin API
• Issuer mismatch: validate iss — staging tokens should not be accepted in production
• Missing custom claims: validate role/permission claims are present after signature verification

Full Debugging Checklist

1. Decode the token — read all claims first
2. Check exp — is the token expired? Is your server clock correct?
3. Check the algorithm in the header against your verifier's allowlist
4. Check the signing key — is it correct? Has it been rotated?
5. Validate iss and aud
6. Check the Authorization header format: Bearer <token> with a space
7. Check for token truncation from copy-paste or URL encoding
8. Check the refresh flow — is the client refreshing before expiry?
9. Enable verbose logging in your JWT library

// Secure JWT verification (Node.js / jsonwebtoken)
jwt.verify(token, publicKey, {
  algorithms: ['RS256'],          // explicit whitelist — never omit this
  issuer: 'https://auth.example.com',
  audience: 'https://api.example.com',
}, (err, payload) => { ... });