401 Unauthorized

Requests lacking valid credentials are rejected with the 401 Unauthorized status code. The server includes this response when Authentication is required and the client has not provided acceptable credentials.

Table of Contents

Usage
OAuth discovery on 401
401 vs 403
Example
How to fix
Code references
See also

Usage

When a 401 Unauthorized error arrives, the client understands valid login credentials are needed before access to the requested resource is granted. The client needs to first log in, or supply credentials as part of the HTTP request. Existing credentials sent with the request are also not valid. This status is distinct from 403 Forbidden, which informs the client the action is not allowed regardless of credentials.

When the server sends a 401 Unauthorized response, the WWW-Authenticate response header is included. This informs the client of the allowed authorization methods. IANA maintains a list of standard authentication schemes, varying in security and popularity. Common Authentication schemes:

Basic

Transmits credentials as ID/password pairs.
Bearer

Also known as token authentication, relies on security tokens generated by the server and returned to the client after a successful login. The client sends these tokens in subsequent requests to access secure resources. The server includes error details when needed: WWW-Authenticate: Bearer error="invalid_token", error_description="Token expired".
Digest

A challenge-response protocol used to authenticate resource requests.
HOBA

Short for HTTP Origin-Bound Authentication, a scheme not requiring the server to store passwords, making the scheme resistant to phishing attacks.
Mutual

Also known as two-way authentication, similar to basic and digest schemes, with the difference the server is guaranteed to know the client's encrypted password. Both client and server authenticate each other before the interaction continues.
AWS4-HMAC-SHA256

An authentication algorithm providing authentication information to Amazon Web Services AWS S3 API Reference.

More than one Authentication method is specified by the server on multiple lines or a single comma-delimited line. When the client has the required credentials, they are sent using the Authorization request header.

OAuth discovery on 401

An API protected by OAuth uses the 401 challenge itself as a discovery mechanism. The WWW-Authenticate header carries a resource_metadata parameter pointing at a document under /.well-known/oauth-protected-resource naming the authorization servers and scopes for the resource. The Model Context Protocol builds its authorization flow on the parameter, so an agent receiving a 401 walks from the challenge to a token without prior configuration.

401 vs 403

401 Unauthorized answers a missing or invalid identity, and 403 answers a valid identity without the required permission. The practical test is whether supplying different credentials changes the outcome. Credentials capable of granting access point to 401. When no credential the requester holds changes the outcome, the answer is 403.

A 401 response carries a WWW-Authenticate header naming the scheme the client needs to satisfy, which is what makes the response actionable. 403 offers no such path, because no credential available to the requester resolves the refusal.

The names invert the meanings and cause most of the confusion. 401 Unauthorized concerns authentication, meaning identity. 403 Forbidden concerns authorization, meaning permission. Reading the names alone points in the wrong direction.

Common pairings in production:

Situation	Status
Expired or missing session token	401
Malformed or invalid API key	401
Valid user, admin-only resource	403
Valid key, plan lacks the feature	403
Request blocked by IP or region rule	403

Returning 401 where 403 applies sends clients into a credential retry loop no credential available to them resolves.

Example

The client requests a resource and the server responds with 401 Unauthorized to indicate the resource is protected. The server indicates support for both Basic and Mutual authorization. The client responds with a username:password pair using the Basic authentication protocol, specified in the Authorization header. The server then transmits the requested resource.

Initial request

GET /documents/tech-news HTTP/1.1
Host: www.example.re

Initial response

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="Documents"
WWW-Authenticate: Mutual

Next request, including Authorization

GET /documents/tech-news HTTP/1.1
Host: www.example.re
Authorization: Basic RXhhbXBsZTphaQ==

Final response

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: 25000

<PDF document included in message body>

How to fix

A 401 Unauthorized means the server requires valid credentials before granting access.

Check the WWW-Authenticate header in the response. This header specifies the expected Authentication scheme (Basic, Bearer, Digest, etc.). Match the client request to the required scheme. Open browser DevTools, select the Network tab, and look for the WWW-Authenticate entry under Response Headers.
Verify credentials. Confirm the username and password, API key, or bearer token are correct. A single typo or whitespace character in the Authorization header value causes rejection. Test credentials in isolation with curl -H "Authorization: Bearer <token>" to rule out application-level issues.
Confirm the token has not expired. Bearer tokens and session tokens have a limited lifetime. Decode a JWT at a local debugger to check the exp claim. Regenerate or refresh the access token through the authentication provider.
Match the Authorization header format to the scheme. Basic expects a Base64-encoded username:password pair. Bearer expects a raw token string. An incorrect format triggers a 401 even with valid credentials. A common mistake is omitting the scheme prefix (sending the token alone without Bearer ).
Regenerate credentials if needed. Rotate the API key or request a new token from the authorization server. Revoked or invalidated credentials always produce this status.
Clear browser cache and Cookies. Stale session cookies or cached Authorization headers conflict with updated credentials. Clear stored data and re-authenticate.
Check server-side authentication configuration. Apache .htpasswd files, nginx auth_basic directives, and .htaccess AuthType rules control access. Verify the credentials file path, the realm name, and the user entry exist. In nginx:
```
auth_basic "Restricted";
auth_basic_user_file /etc/nginx/.htpasswd;
```
In Apache:
```
AuthType Basic
AuthName "Restricted"
AuthUserFile /etc/apache2/.htpasswd
Require valid-user
```
Verify OAuth scopes and audience claims. An access token with correct credentials but wrong scopes or an aud claim not matching the resource server still triggers 401. Confirm the token is issued for the target API.

Code references

.NET

HttpStatusCode.Unauthorized

Rust

http::StatusCode::UNAUTHORIZED

Rails

:unauthorized

http.StatusUnauthorized

Symfony

Response::HTTP_UNAUTHORIZED

Python3.5+

http.HTTPStatus.UNAUTHORIZED

Java

java.net.HttpURLConnection.HTTP_UNAUTHORIZED

Apache HttpComponents Core

org.apache.hc.core5.http.HttpStatus.SC_UNAUTHORIZED

Angular

@angular/common/http/HttpStatusCode.Unauthorized