401 - Unauthorized
HTTP 401 Unauthorized means the origin or gateway could not authenticate this request and is asking the client to present valid credentials for the target resource.
Last reviewed: April 12, 2026|Source-backed guidance under our editorial policy
Start Here
Use the closest compare guide, playbook, or adjacent error page to narrow the decision faster before you start changing production systems.
This page is part of the Error Reference library. Learn more about the project or report a correction.
What Does Unauthorized Mean?
Treat 401 as an authentication failure, not a permission failure. The useful tuple is challenge, credential, and route: what auth scheme the server demanded, what credential the client sent, and whether that credential survived every hop to the handler.
Common Causes
- -Authorization header never reaches the origin because a proxy, redirect, CDN rule, or middleware path strips it before auth evaluation.
- -Bearer token is expired, not yet valid, or rejected due to clock skew on the issuing or consuming system.
- -JWT audience (
aud), issuer (iss), or realm targets another API, so signature validation passes but authentication still fails. - -Session cookie is missing on this route because domain, path, SameSite, secure-cookie, or CSRF coupling is wrong in the live environment.
- -Client sends the wrong auth scheme entirely, such as API key or Basic auth while the server is challenging for Bearer.
How to Fix Unauthorized
- 1Capture the full 401 response, especially the
WWW-Authenticatechallenge, request ID, and route that failed. - 2Verify the credential leaving the client is the same credential that reaches the origin after every proxy and redirect hop.
- 3Decode the token or inspect session state for
exp,nbf,aud,iss, cookie scope, and realm compatibility with the exact route. - 4Replay the same request with a known-good credential path before changing permissions or application logic.
Step-by-Step Diagnosis for Unauthorized
- 1Capture the request ID, route, auth scheme used by the client, and the exact
WWW-Authenticateheader from the 401 response. - 2Decode the credential and validate
exp,nbf,aud,iss, realm, and scope against the resource that returned 401. - 3Trace
Authorizationheaders or session cookies across CDN, ingress, proxy, and application middleware boundaries. - 4Verify clock sync, token refresh timing, and session-cookie settings in the environment where 401 occurs.
- 5Retry the same request with a known-good token or session from the same environment to isolate route-specific auth drift.
- 6Compare the failing route against a healthy route that uses the same identity provider to pinpoint the broken hop or config difference.
Seen in Production
- -API returns
WWW-Authenticate: Bearer realm="api", error="invalid_token", error_description="The access token expired"even though the frontend still shows the user as signed in. - -One route behind a gateway rewrite returns 401 while sibling routes succeed because the rewrite branch drops the
Authorizationheader before the upstream service sees it. - -Staging works, production fails, and the real difference is a secure session cookie that is not sent on the production subdomain path.
WWW-Authenticate and Token Claim Review
- -Read the server challenge literally and verify the client is satisfying that exact scheme and realm (example: server demands Bearer for
api://billing, but token was minted forapi://profile). - -Inspect token claims and session metadata before touching policy layers (example: token is structurally valid but expired or not yet valid because of skew).
Transport and Session Boundary Checks
- -Trace header and cookie continuity across ingress, CDN, reverse proxy, and app middleware (example: auth header is present at the edge but missing in the application log).
- -Validate cookie domain/path/SameSite behavior on the exact failing route, especially when auth works on HTML pages but fails on API subpaths.
Wrong Fix to Avoid
- -Do not add broader permissions to the identity before proving authentication is valid; 401 is usually the wrong place to edit authorization policy.
- -Do not only test with a browser session if the failing client is a server-to-server call using Bearer tokens or API keys.
Implementation Examples
GET /v1/reports/export HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOi...
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api", error="invalid_token", error_description="The access token expired"
Content-Type: application/json
X-Request-Id: req_7c1c7a
{
"error": "Unauthorized",
"requestId": "req_7c1c7a"
}curl -i https://api.example.com/v1/reports/export \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Accept: application/json"Seen in Production
Expired token survives a deploy because refresh cache is stale
Frequency: common
Example: A subset of requests receives 401 for ten minutes after restart because workers continue serving an expired token from cache.
Fix: Invalidate cached credentials on restart and refresh before expiry with skew-aware thresholds.
Gateway rewrite drops Authorization on one path only
Frequency: common
Example: Healthier routes authenticate fine, but /v1/reports/export always returns 401 because the rewrite branch strips auth headers.
Fix: Patch the rewrite policy and add route-level header continuity tests from edge to origin.
Wrong audience token is used against a sibling API
Frequency: medium
Example: Frontend holds a token for api://profile, but billing endpoints challenge for api://billing and return 401 consistently.
Fix: Request the correct audience for that API and verify the route-specific challenge contract in tests.
Debugging Tools
- -curl -v or browser network capture with raw auth headers
- -JWT decoder or token introspection endpoint
- -Gateway, CDN, and origin logs keyed by request ID
- -Identity provider audit logs and session-debug tools
- -NTP and clock-skew monitoring for token validation hosts
How to Verify the Fix
- -Replay the exact failing request and confirm the same route now returns a non-401 result with valid credentials.
- -Verify application or gateway logs show the credential arriving intact and the auth middleware accepting it.
- -Confirm token refresh or session renewal works across at least one full credential lifetime without intermittent 401 spikes.
- -Check that adjacent routes with the same auth dependency still behave correctly and have not regressed.
How to Prevent Recurrence
- -Standardize auth libraries, token validation settings, and proxy forwarding behavior across environments.
- -Add pre-deploy smoke tests that verify
WWW-Authenticatebehavior, session cookies, and token audience on critical routes. - -Monitor clock skew, token refresh failure rate, and header-drop incidents at ingress boundaries.
Pro Tip
- -alert on 401 spikes grouped by
WWW-Authenticatechallenge and route so auth-scheme drift is visible before users report it.
Decision Support
Compare Guide
401 Unauthorized vs 403 Forbidden: Auth vs Access Denied
Fix 401 Unauthorized vs 403 Forbidden by separating authentication failures from authorization denials, then apply the right login or permission fix fast.
Playbook
Auth Incident Playbook (401 / UNAUTHENTICATED)
Use this playbook to separate missing, expired, or invalid identity proof from authorization and transport failures, and apply credential-source-correct fixes safely.
Playbook
CORS Error Fix Playbook (Preflight / Origin / Credentials)
Use this playbook to separate browser-enforced cross-origin policy failures from server-side CORS header and route defects and apply strict origin and credential controls safely.
Official References
Provider Context
This guidance is specific to HTTP services. Always validate implementation details against official provider documentation before deploying to production.