401 Unauthorized
This is an educational reference page about HTTP 401 Unauthorized. The page itself is served as 200 OK so it can be indexed as HTTP documentation.
The request lacks valid authentication credentials for the target resource. The response must include a WWW-Authenticate challenge.
Specification
Registered in the IANA HTTP Status Code Registry as Unauthorized. Defined in RFC 9110, Section 15.5.2.
What it means
HTTP 401 Unauthorized means the request did not include valid authentication credentials. The name is misleading because 401 covers authentication, meaning who the client is. Permission checks belong to 403. RFC 9110 requires a 401 response to include a WWW-Authenticate header with at least one challenge. If the request did include credentials, 401 means the server refused those credentials.
When to use it
- Return 401 when the Authorization header is missing.
- Return 401 when a token is expired, revoked, or malformed. RFC 6750 maps the Bearer error invalid_token to 401.
- Return 403 instead when the credentials are valid but the user lacks permission.
Common causes
- No Authorization header, or a session cookie that expired.
- An expired or revoked access token.
- A token sent with the wrong scheme, such as Token abc instead of Bearer abc.
- A proxy or CDN that strips the Authorization header before it reaches the origin.
Headers involved
- WWW-Authenticate is required on 401. It names the scheme and any parameters, such as Bearer realm="api".
- Authorization carries the client's credentials on the retry.
- Proxy authentication uses 407 with Proxy-Authenticate and Proxy-Authorization instead.
How to fix it
- Send credentials in the scheme the server's WWW-Authenticate header names.
- Refresh the access token and retry once. If the retry also fails, ask the user to sign in again.
- Check that proxies and redirects keep the Authorization header. Many HTTP clients drop it on cross-origin redirects.
Examples
Expired Bearer token
GET /api/me 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="Token expired"
Content-Type: application/json
{
"error": "invalid_token"
}No credentials sent
GET /admin/reports HTTP/1.1
Host: example.com
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="admin", charset="UTF-8"Common mistakes
- Leaving out WWW-Authenticate. RFC 9110 requires it on every 401.
- Returning 401 to a signed-in user who lacks a role. That is 403, and returning 401 can send the client into a login loop.
- Sending a Basic challenge from a JSON API. Browsers show a native login dialog when they see WWW-Authenticate: Basic.
Developer notes
The 401 vs 403 rule: 401 means the server does not know who you are, or does not accept the credentials you sent. 403 means it knows who you are and still says no. A client can fix a 401 by authenticating; a 403 needs different permissions.
Questions
What does HTTP 401 Unauthorized mean?
HTTP 401 means the request lacks valid authentication credentials. The client should authenticate, or refresh its credentials, and try again.
Is WWW-Authenticate required with 401?
Yes. RFC 9110 says a server generating a 401 response MUST send a WWW-Authenticate header with at least one challenge.
Should an expired token return 401 or 403?
Return 401. The client can fix it by getting a new token. RFC 6750 maps invalid_token, which covers expired tokens, to 401.
See also
Header and content rules
What RFC 9110 says about a 401 response, quoted from the RFC. The 4xx class rules also apply.
- MUST (server; WWW-Authenticate): Send WWW-Authenticate with at least one challenge for the target resource. Table row
The server generating a 401 response MUST send a WWW-Authenticate header field (Section 11.6.1) containing at least one challenge applicable to the target resource. RFC 9110 §15.5.2
The same rule is in the response obligations table and its JSON.