JWT 401/403 Troubleshooting

Diagnose failed auth requests (401/403) step by step from headers and token information. No input is sent to a server.

Status

Runs in your browser. No input is sent to a server. Mask sensitive values before pasting.

How to use

Paste 401/403 status and headers first, then add JWT if available. Diagnose exp/nbf/iat together with WWW-Authenticate.

Notes (this tool)

  • This does not perform full signature/key validation. Use JWT Verifier when needed.
  • Time checks are based on your device clock. Adjust “clock skew allowance” if server clock differs.

About this page

What does this tool do?

Analyzes HTTP status (401/403), Authorization, WWW-Authenticate, and JWT payload together to identify likely failure points.

A first-pass hub for cases like “unknown 401 cause” or “403: insufficient scope vs policy mismatch.”

401 vs 403 basics

  • 401: authentication failed (missing token, expired token, bad signature, etc.)
  • 403: authenticated but not authorized (insufficient scope/role or policy deny)
  • WWW-Authenticate is critical on 401 (error / error_description / scope)

Common symptoms

  • 401 returned even though Authorization header is present
  • 401 spikes right after token refresh/deployment
  • JWT decodes fine but API still returns 403
  • 401/403 behavior differs by environment (e.g., production only)

Debugging workflow (recommended)

  • Paste status line and request/response headers
  • Paste JWT (or payload JSON)
  • Classify 401 vs 403 first, then inspect claims/time/scope
  • Use WWW-Authenticate error/scope as the basis for next actions

Practical check points

  • Authorization header uses proper Bearer format
  • exp / nbf / iat align with current time (including clock skew)
  • aud / iss match server expectations
  • scope/scp/roles satisfy required permissions
  • WWW-Authenticate indicates invalid_token / insufficient_scope

Recommendations (operations)

  • Return WWW-Authenticate on 401 and include explicit error codes
  • Log token validation reasons (exp/aud/iss/scope)
  • Document server clock sync (NTP) and tolerated skew
  • Keep authentication failure (401) and authorization deny (403) clearly separated
  • OAuth Bearer Diagnostic
  • Authorization Inspect
  • WWW-Authenticate Inspect
  • JWT Decoder
  • JWT Verifier
  • JWT TTL Check
  • JWT Claim Audit
  • JWT Clock Skew Check

What this tool does

  • Classify and diagnose 401/403 responses
  • Check Authorization and WWW-Authenticate consistency
  • Evaluate JWT time claims (exp/nbf/iat)
  • Provide hints for aud/iss/scope mismatches

Operational notes

  • This page assists diagnosis only. Final decisions must rely on implementation, policy, and logs.
  • Signature verification is not fully performed here; use JWT Verifier for cryptographic checks.
  • Mask sensitive data before pasting.

Referenced specs

  • RFC 9110 (HTTP Semantics: 401/403)
  • RFC 6750 (OAuth 2.0 Bearer Token Usage)
  • RFC 7519 (JWT)

FAQ

What happens if 401 and 403 are mixed up?

Client re-auth and retry behavior can break, making incident diagnosis harder.

Why can a seemingly valid JWT still cause 401?

Typical reasons include signature mismatch, aud/iss mismatch, clock skew, and key-rotation timing issues.

What should I check first on 403?

Check required scope/role vs token claims, insufficient_scope in WWW-Authenticate, and endpoint authorization policy.

References

  1. RFC 9110
  2. RFC 6750
  3. RFC 7519
  4. MDN: WWW-Authenticate

Page-specific case studies

Use this page to reproduce 401 vs 403 paths by correlating response headers and claims.

  • On 401, inspect WWW-Authenticate error and description.
  • On 403, inspect missing scope or role and policy conditions.
  • For time-based rejects, compare exp and nbf with server clock.

Page-specific implementation checklist

  • Document precise 401 and 403 return conditions in API specs.
  • Keep WWW-Authenticate formats consistent across implementations.
  • Standardize messages for missing claims or scopes.
  • Capture minimal token metadata during incidents.

These links are generated from site_map rules in recommended diagnostic order.

  1. OAuth Bearer Diagnostic — Diagnose consistency between Bearer and WWW-Authenticate
  2. Authorization Inspect — Parse Authorization header formats
  3. WWW-Authenticate Inspect — Parse WWW-Authenticate challenges
  4. JWT Decoder — Decode and pretty-print JWT header/payload
  5. JWT Verifier — Verify JWT signatures (HS/RS/ES)
  6. JWT TTL Check — Calculate validity window and remaining TTL from exp/iat/nbf
  7. JWT Claim Audit — Audit missing required/recommended JWT claims
  8. JWT Clock Skew Check — Detect timestamp skew across iat/nbf/exp

Auth

Trace auth failures across Bearer, WWW-Authenticate, and JWT