401 Unauthorized
Description
The 401 Unauthorized status code indicates that the request lacks valid authentication credentials for the target resource. The client must authenticate itself to get the requested response. This status code is similar to 403 Forbidden, but specifically indicates that the client must provide or fix their authentication credentials.
This status code is commonly used when: - A user is not logged in but tries to access a protected resource - Authentication credentials (like API keys or tokens) are missing - Authentication credentials have expired - Authentication credentials are invalid
The server should include a WWW-Authenticate header field containing at least one challenge applicable to the target resource. This header helps the client understand what authentication mechanisms are available.
Despite its name, the 401 Unauthorized status code actually refers to "unauthenticated" rather than "unauthorized" - it's about whether the client has identified itself properly, not about permissions.
Syntax
The server responds with a 401 Unauthorized status and includes authentication information:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: [authentication scheme] realm="[realm]"
Content-Type: application/json
Content-Length: [length in bytes]
{
"error": "Unauthorized",
"message": "Authentication required to access this resource"
}
Examples
Basic Authentication Example
A client attempts to access a protected resource without providing credentials:
Client Request:
Server Response:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="User Visible Realm"
Content-Type: application/json
Content-Length: 95
{
"error": "Unauthorized",
"message": "Authentication required to access this resource"
}
Bearer Token Authentication Example
A client attempts to access an API with an expired token:
Client Request:
GET /api/user/profile HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Server Response:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", error_description="The access token has expired"
Content-Type: application/json
Content-Length: 128
{
"error": "Unauthorized",
"message": "The access token has expired",
"expires_at": "2023-06-15T12:30:45Z"
}
API Key Authentication Example
A client attempts to access an API with an invalid API key:
Client Request:
Server Response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json
Content-Length: 102
{
"error": "Unauthorized",
"message": "Invalid API key provided",
"documentation_url": "https://api.example.com/docs/auth"
}
Summary
The 401 Unauthorized status code is a critical component of web security, indicating that a client must authenticate (or re-authenticate) to access a protected resource. It's distinct from 403 Forbidden in that it specifically indicates an authentication problem rather than a permissions problem. By including the WWW-Authenticate header, servers can guide clients on how to properly authenticate for subsequent requests. This status code is widely used in web applications, APIs, and any system that requires user authentication before granting access to protected resources.