The WWW-Authenticate response header defines the authentication method that should be used to gain access to a resource. It is sent by the server in 401 Unauthorized responses.

Syntax and structure

The header format specifies an authentication scheme and optional auth parameters:

WWW-Authenticate: <type> realm=<realm> [, <param>...]

Bearer token challenge (RFC 6750)

In modern REST and GraphQL APIs using OAuth 2.0 or JWTs, servers return Bearer challenges with error descriptions:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api.example.test", error="invalid_token", error_description="The access token expired"

Basic authentication challenge (RFC 7617)

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="Secure Administration Area"

When a web browser receives a Basic challenge, it automatically presents a native login dialog prompting the user for username and password.

Protocol requirements

According to RFC 9110 Section 11.6.1:

  • A server generating a 401 Unauthorized response MUST send at least one WWW-Authenticate header field containing at least one challenge.
  • The server may include multiple challenges (or multiple WWW-Authenticate header fields) if it supports multiple authentication schemes (e.g., Bearer and ApiKey).

How to inspect with curl

Inspect the challenge header returned by an unauthenticated endpoint:

curl -i https://api.example.test/v1/protected-resource

Key takeaway

The WWW-Authenticate header is a mandatory response header on HTTP 401 responses that communicates the expected authentication scheme, realm, and error details to the client. It enables clients to negotiate credentials or initiate token refresh flows.