WWW-Authenticate

The HTTP WWW-Authenticate response header indicates which Authentication schemes a server accepts for accessing a protected resource.

Table of Contents

Usage
Directives
Example
Takeaway
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.

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"

Takeaway

The HTTP WWW-Authenticate response header challenges the client to provide credentials for a protected resource, defining which authentication schemes and parameters the server accepts in the Authorization header.