JWT 401/403 Diagnostic Playbook

401 usually indicates authentication failure, while 403 indicates authorization denial. Separate header-level and token-level checks for reproducible diagnosis.

First split to make

Diagnostic steps

  1. 1) Validate scheme and format with Authorization Inspect
  2. 2) Inspect error/description/scope with WWW-Authenticate Inspect
  3. 3) Read exp/nbf/aud/iss/scope with JWT Decoder
  4. 4) Run signature, kid, and iss/aud checks with JWT Verifier
  5. 5) Quantify expiry and clock drift with JWT TTL Check

Typical causes

Operational checklist

Post-fix verification

Tools to use

FAQ

How should 401 and 403 be separated?
Use 401 for authentication failures and 403 for authorization denials. Separate WWW-Authenticate handling from scope/role checks.
Can a token return 401 even before exp?
Yes. Signature mismatch, iss/aud mismatch, nbf constraints, and clock skew can all produce 401.

Referenced specs

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

  1. JWT 401/403 Troubleshooting — Troubleshoot 401/403 auth failures from headers and JWT claims
  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. Symptom-Based Diagnostic Guide (Start Here) — A central hub that routes cache/CORS/JWT/MIME incidents into shortest symptom-first diagnostic paths
  8. How to Diagnose Missing 304 Responses — Trace ETag/Last-Modified and If-* round trips to isolate missing 304 behavior

Scenario Clusters

Operational incident scenarios that route you into the shortest diagnostic path