JWT Decoder for Authentication Debugging: A Complete Workflow Guide
Learn how to use a JWT decoder to debug authentication failures fast. Step-by-step workflow for inspecting tokens, catching expired claims, and fixing 401 errors.
The Problem
You're debugging a failed authentication request. The API returns 401 Unauthorized. Your logs show the token was sent, but you have no idea why it's being rejected — is the signature wrong? Is the token expired? Does it have the right audience claim? Without decoding the token, you're debugging blind.
Why This Matters
JWT tokens carry all the authentication context your API needs to make authorization decisions: user ID, roles, permissions, expiry time, issuer, audience. When auth breaks, the token payload is the first place to look. Developers who know how to quickly decode and inspect JWTs in context — not just in isolation — resolve authentication bugs in minutes instead of hours. This workflow integrates JWT decoding into your everyday debugging process, alongside your API client and browser DevTools.
Step-by-Step Instructions
Capture the token from the failing request
Open browser DevTools → Network tab. Find the failing API request. In the Request Headers panel, copy the full value of the Authorization header (starts with Bearer eyJ...). Strip the Bearer prefix — you just need the token string itself.
Decode and inspect the header
Paste the token into the JWT Decoder below. First check the header: verify the alg field matches what your server expects (HS256, RS256, ES256). A mismatch here causes immediate rejection regardless of other claims.
Check expiry and issued-at timestamps
In the decoded payload, find exp (expiry) and iat (issued at). The decoder converts these Unix timestamps to human-readable dates. If exp is in the past, the token is expired — your client needs to refresh it. If iat is in the future, your server's clock may be skewed.
Validate audience and issuer claims
Look for aud (audience) and iss (issuer) claims. Your server validates these against its configuration. For example, if your server expects aud: api.myapp.com but the token has aud: app.myapp.com, the request fails. Use Text Diff Checker to compare expected vs actual claim values side-by-side.
Inspect role and permission claims
Check custom claims like role, permissions, scope, or groups. A 403 Forbidden (not 401) usually means the token is valid but lacks the required permission. Confirm your identity provider is issuing the correct claims for this user's account.
Cross-reference with your API's expected schema
Use JSON Formatter to paste both your decoded token payload and your server's expected claims config side-by-side. Beautifying both as formatted JSON makes structural mismatches immediately obvious. Fix the claim in your auth provider or update your server's validation logic accordingly.
Try It Now — JWT Decoder
Open full page →All processing happens in your browser — no data is sent to any server.
Before & After Example
Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyXzQ1NiIsImVtYWlsIjoiYm9iQGV4YW1wbGUuY29tIiwicm9sZSI6InZpZXdlciIsImF1ZCI6InN0YWdpbmcuYXBpLmNvbSIsImlhdCI6MTcwOTgwMDQwMCwiZXhwIjoxNzA5ODA0MDB9.sig
{
"sub": "user_456",
"email": "[email protected]",
"role": "viewer", // ← Needs "admin" for this endpoint
"aud": "staging.api.com", // ← Server expects "production.api.com"
"iat": 1709800400, // Issued: 2026-03-07 10:00:00 UTC
"exp": 1709804000 // Expired: 2026-03-07 11:00:00 UTC ← EXPIRED!
}
// Root cause: 3 issues found in < 30 seconds
Frequently Asked Questions
What's the difference between a 401 and a 403 JWT error?
401 Unauthorized means the token itself is invalid — expired, bad signature, wrong algorithm, or missing entirely. 403 Forbidden means the token is valid but the user lacks permission. When debugging, decode the token first: if it looks correct, the issue is likely a permission/role claim rather than the token structure.
Can I debug JWTs from mobile apps the same way?
Yes. Use a proxy tool like Charles or mitmproxy to intercept HTTPS traffic from your mobile app. The JWT will appear in the Authorization header just like in a browser. Copy it and paste into the JWT Decoder to inspect claims. This works for iOS, Android, and React Native apps.
How do I handle JWT debugging in a microservices architecture?
In microservices, JWTs may be modified at each service boundary (added claims, re-signed). Log the raw token at each service entry point and decode each one separately. Compare the payloads using Text Diff Checker to see exactly what changed between services — this quickly reveals which service is modifying or stripping claims.
Related Workflows
Want the full JWT Decoder experience?
Open the standalone tool for more space, keyboard shortcuts, and additional features.
Open JWT Decoder →