WWW-Authenticate: the challenge that comes with a 401
WWW-Authenticate accompanies a 401 response and states which authentication schemes the server accepts, along with parameters such as the realm.
At a glance
- Direction
- Response only, and required on any 401 Unauthorized.
- Defined in
- RFC 9110, with the Bearer parameters in RFC 6750
- When absent
- A 401 with no challenge is malformed, and clients have nothing to act on.
- Required on
- Every 401 Unauthorized response
- realm
- A label for the protection space. Browsers show it in the credentials dialog.
- Bearer parameters
- error="invalid_token" and error_description, for token failures
- Multiple schemes
- Send several challenges, and the client picks the strongest it supports.
In detail
The header is what makes a 401 actionable. It names a scheme, so the client knows what kind of credential to produce, and it may carry parameters that scope or explain the challenge. A 401 without it tells the client only that something is wrong, with no indication of how to fix it, which is why the specification requires the header on that status.
The realm parameter identifies the protection space. In a browser it appears in the credentials dialog, and clients use it to decide which stored credentials apply, so a stable and meaningful realm matters more than it looks. Changing it invalidates whatever the client had associated with the old one.
For bearer tokens the useful part is the error parameter. Answering with error="invalid_token" distinguishes an expired token, which the client should refresh and retry, from a missing one, which means signing in again. Without that distinction every client has to guess, and most guess by retrying in a loop.
Choose the status carefully. A 401 means the request lacked valid credentials and the client may retry with different ones. A 403 means the credentials were understood and are not sufficient, and it carries no challenge, because there is nothing useful for the client to send instead.
Examples
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="Reporting API", charset="UTF-8"HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api", error="invalid_token", error_description="The access token expired"This is the response a client should react to by refreshing the token rather than prompting the user again.
Things that catch people out
- Sending a Basic challenge on a browser facing API makes the browser show a native credentials dialog, which is almost never the experience you wanted.
- A 401 with no challenge header is malformed, and some clients treat it as a hard failure rather than retrying with credentials.
- Using 401 when you meant 403 sends the client back to sign in for a permission problem that signing in again will not solve.
Try it: HTTP Headers Checker
Check a live URL or paste headers you already have. It grades six security headers from A+ to F and lists every other header the response returned.
HTTP Headers Checker
LOCAL · Browser-OnlyView HTTP response headers for any URL
Enter any website URL to fetch and analyze its HTTP response headers. We'll automatically add https:// if needed.
Why Check Security Headers?
Security headers protect your website against common attacks like XSS, clickjacking, and MIME sniffing. They're set by your web server and cost nothing to implement. Missing security headers are one of the most common findings in security audits.
Related HTTP headers
All http headers →Authorization: credentials on a request
How the Authorization header is structured, how Basic and Bearer differ, why it is dropped across a cross-host redirect, and how it interacts with caching.
Proxy-Authorization: credentials for the proxy itself
How proxy authentication differs from origin authentication, why the header is hop by hop, what a 407 means, and how tunnelled connections handle it.
Set-Cookie: attributes, SameSite and cookie prefixes
Every Set-Cookie attribute explained, why SameSite=None needs Secure, what the __Host- prefix guarantees, and how Max-Age and Expires interact.
Retry-After: when to try the request again
The two formats Retry-After accepts, which statuses it belongs on, why a fixed value causes synchronised retries, and how clients should treat it.
Cookie: what the browser sends back
How the Cookie header is formatted, why attributes never come back, how the browser decides which cookies to include, and what the size limits are.
Host: which site the request is for
Why Host is mandatory in HTTP/1.1, how it maps to the authority in HTTP/2 and HTTP/3, and why trusting it to build URLs creates a real vulnerability.
Tools for this
- HTTP Request Builder Free online HTTP request builder - build and test HTTP requests with custom headers and body
- HTTP Headers Checker Free online HTTP headers checker - view HTTP response headers for any URL