/ HTTP Status Codes

401 Unauthorized

The 401 Unauthorized status code is an HTTP response status code that signifies that the request requires authentication and the client has failed to provide valid credentials or the provided credentials are insufficient to access the requested resource. This guide will provide an in-depth understanding of the 401 Unauthorized status code, its usage, and examples of request and response scenarios.

Understanding 401 Unauthorized

When a client sends a request to a protected resource on a server, the server may require the client to authenticate itself by providing valid credentials. If the client fails to provide valid credentials or the provided credentials do not grant access to the requested resource, the server responds with a 401 Unauthorized status code.

The 401 Unauthorized status code is part of the HTTP/1.1 standard (RFC 7235) and is categorized under the class of status codes referred to as “Client Error Responses.” These status codes indicate that the request contains bad syntax, cannot be fulfilled by the server, or requires further action from the client.

It is essential to understand that the 401 Unauthorized status code does not imply that the server could not authenticate the client. Instead, it indicates that the client must provide authentication credentials for the requested resource.

When to Use 401 Unauthorized

The 401 Unauthorized status code should be used in situations where:

  1. The request requires authentication, but the client has not provided any credentials.
  2. The provided credentials are invalid, expired, or insufficient to access the requested resource.

Understanding WWW-Authenticate Header

When a server responds with a 401 Unauthorized status code, it must also include a WWW-Authenticate header in the response. This header informs the client about the type of authentication required and any additional information needed to authenticate the request.

The WWW-Authenticate header may contain multiple challenges, each specifying a different authentication scheme. The client can choose the most suitable authentication scheme and provide the required credentials accordingly.

Here’s an example of a WWW-Authenticate header with two different authentication schemes:

WWW-Authenticate: Basic realm="example", Bearer realm="example"

In this example, the server supports both Basic and Bearer authentication schemes. The client can choose either of these schemes to authenticate the request.

Request and Response Examples

Example 1: Request without Authentication

Request:

GET /protected/resource HTTP/1.1
Host: example.com

Response:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="example"
Content-Type: text/html; charset=UTF-8

<!DOCTYPE html>
<html>
<head>
  <title>401 Unauthorized</title>
</head>
<body>
  <h1>Unauthorized</h1>
  <p>You must provide valid authentication credentials to access this resource.</p>
</body>
</html>

In this example, the client sends a request without any authentication credentials. The server responds with a 401 Unauthorized status code and a WWW-Authenticate header indicating that Basic authentication is required.

Example 2: Request with Invalid Credentials

Request:

GET /protected/resource HTTP/1.1
Host: example.com
Authorization: Basic aW52YWxpZDpleGFtcGxl

Response:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="example"
Content-Type: text/html; charset=UTF-8

<!DOCTYPE html>
<html>
<head>
  <title>401 Unauthorized</title>
</head>
<body>
  <h1>Unauthorized</h1>
  <p>The provided authentication credentials are invalid or insufficient to access this resource.</p>
</body>
</html>

In this example, the client sends a request with invalid Basic authentication credentials. The server responds with a 401 Unauthorized status code and a WWW-Authenticate header indicating that the provided credentials are invalid or insufficient.

Summary

In conclusion, the 401 Unauthorized status code is an HTTP response status code that indicates that the client must provide valid authentication credentials to access the requested resource. When responding with a 401 Unauthorized status code, the server must include a WWW-Authenticate header to inform the client about the required authentication scheme and any additional information needed to authenticate the request.

Was this helpful?

Thanks for your feedback!