401 Unauthorized

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.

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: example.com

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: example.com
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 ” 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