WWW-Authenticate

When a client requests a protected resource without valid credentials, the server needs to communicate which schemes are accepted. The WWW-Authenticate response header carries one or more Authentication challenges alongside a 401 status code.

Table of Contents

Usage
Directives
Example
Common configuration mistakes
Crawlers and authentication
See also

Usage

When a client requests a protected resource without valid credentials, the server responds with a 401 status code and includes the WWW-Authenticate header. This header carries one or more authentication challenges, each specifying a scheme and any parameters the client needs to construct valid credentials.

After receiving the challenge, the client resubmits the request with an Authorization header containing the credentials formatted according to the selected scheme. The server validates the credentials and returns the requested resource on success.

Multiple challenges in a single response allow the server to offer several schemes simultaneously. The client selects the strongest scheme both sides support. Challenges appear on separate header lines or in a single comma-separated line.

The equivalent header for proxy-level authentication is Proxy-Authenticate, which triggers a 407 response instead of a 401.

Directives

scheme

The scheme identifies the authentication method. Registered schemes are maintained by IANA. The most common schemes in practice are described below.

Basic sends a Base64-encoded username:password pair. The scheme accepts a realm parameter and an optional charset parameter (typically UTF-8).

Bearer authenticates with an opaque access token, most commonly issued through an OAuth flow. The scheme supports realm, scope, and error parameters. The scope parameter lists the permissions the token must carry. The error parameter communicates specific failure reasons like invalid_token or insufficient_scope.

Digest improves on Basic by hashing credentials with a server-provided nonce, preventing the password from traveling in cleartext. Required parameters include realm, nonce, and qop (quality of protection). Optional parameters include algorithm, opaque, and stale.

Negotiate initiates SPNEGO-based authentication, typically backed by Kerberos or NTLM in enterprise environments. The scheme carries a Base64-encoded SPNEGO token when the negotiation is in progress.

realm

The realm parameter is an optional string defining the protection space. The value helps users identify which credentials are needed. A server protecting different areas assigns distinct realm values to each.

token68

The token68 syntax is an alternative credential encoding allowed by the HTTP authentication framework. The value uses a restricted character set (alphanumerics, -, ., _, ~, +, /) with optional trailing = padding.

resource_metadata

The resource_metadata parameter carries the URL of an OAuth protected resource metadata document, served under /.well-known/oauth-protected-resource. The document lists the resource identifier, the authorization servers issuing tokens for the resource, and the supported scopes, letting a client discover where to obtain a token from the challenge alone.

WWW-Authenticate: Bearer resource_metadata=
  "https://api.example.re/.well-known/oauth-protected-resource"

The Model Context Protocol relies on the parameter for authorization discovery: an MCP server answering 401 points the client at its metadata, and the client follows the chain to the authorization server without prior configuration.

Example

A server protecting a resource with Basic authentication returns a challenge including the realm name displayed to the user.

WWW-Authenticate: Basic realm="Staging Environment"

A Bearer token challenge communicates the required scope and signals an expired token with the error parameter.

WWW-Authenticate: Bearer realm="api.example.re", scope="read write", error="invalid_token"

A Digest challenge includes the server-generated nonce and quality of protection setting.

WWW-Authenticate: Digest realm="admin@example.re", nonce="7ypf/xlj9XXwfDPEoM4URrv/xwf94BcCAzFZH4GiTo0v", qop="auth", algorithm=SHA-256

A server offering multiple schemes lists them so the client picks the strongest option.

WWW-Authenticate: Negotiate
WWW-Authenticate: Bearer realm="api.example.re"
WWW-Authenticate: Basic realm="api.example.re"

A full Basic authentication handshake. The client first requests a protected resource without credentials:

GET /admin HTTP/1.1
Host: example.re

The server responds with 401 and a Basic challenge:

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

The client retries with an Authorization header containing the Base64-encoded username:password pair:

GET /admin HTTP/1.1
Host: example.re
Authorization: Basic dXNlcjpwYXNz

The server validates the credentials and returns the resource:

HTTP/1.1 200 OK
Content-Type: text/html

Common configuration mistakes

A 401 response carries WWW-Authenticate in every case. Responses omitting the header leave browsers with no scheme to satisfy, so no credential prompt appears and the request fails silently. API clients hit the same wall, retrying without knowing which scheme to use. Returning 403 instead communicates a permission problem on valid credentials, which is a different condition.

Basic credentials travel Base64-encoded rather than encrypted, so the scheme belongs on HTTPS connections only. Base64 decoding is trivial and carries no protective value.

Reverse proxies terminate authentication before the application sees the request. nginx auth_basic with auth_basic_user_file and Apache AuthType Basic with Require valid-user both answer the challenge themselves, so an application returning its own challenge behind either produces two prompts. nginx forwards the Authorization header to the origin by default on a proxy_pass. Apache forwards the header when proxying, while CGI and FastCGI scripts see credentials only after CGIPassAuth is enabled.

Crawlers and authentication

Content behind an authentication challenge stays out of search results. Googlebot sends no credentials, receives 401, and treats the URL the same way as other 4xx responses, removing the URL from the index.

Staging environments protected with Basic authentication are safe from indexing for the same reason, and the protection lifts the moment the challenge does. A staging host reachable without credentials competes with production for the same content, so the challenge stays in place until the host is retired.