WWW-Authenticate
response headerauthentication & cookies
Sent with a 401 to tell the client which authentication scheme to use, and sometimes why the last attempt failed.
A 401 Unauthorized response should include WWW-Authenticate, naming the scheme the client should use. With Basic, browsers show their built-in login dialog. With Bearer, OAuth servers add an error parameter that tells clients whether to refresh the token or give up.
Syntax
WWW-Authenticate: <scheme> realm="<realm>"[, <param>="<value>"]
Defined in RFC 9110 §11.6.1 — WWW-Authenticate.
Values
| Basic realm="…" | username and password; browsers show a login prompt |
|---|---|
| Bearer | send an access token |
| Bearer error="invalid_token" | the token is expired, revoked or malformed |
| Bearer error="insufficient_scope" | valid token, missing permissions (sent with 403) |
Examples
WWW-Authenticate: Bearer realm="api", error="invalid_token", error_description="The access token expired"
tells the client to refresh its token
WWW-Authenticate: Basic realm="Staging", charset="UTF-8"
a password-protected staging site
Good to know
- To avoid the browser's login dialog in a single-page app, don't send
Basic— useBeareror a custom scheme. - Cross-origin JavaScript can only read this header if you list it in
Access-Control-Expose-Headers.
How to set WWW-Authenticate
res
.status(401)
.set("WWW-Authenticate", 'Bearer realm="api", error="invalid_token"')
.json({ error: "invalid_token" });return Response.json(
{ error: "invalid_token" },
{
status: 401,
headers: { "WWW-Authenticate": 'Bearer realm="api", error="invalid_token"' },
},
);location / {
auth_basic "Staging"; # sends WWW-Authenticate: Basic realm="Staging"
auth_basic_user_file /etc/nginx/.htpasswd;
}Check it
Fetch only the response headers and filter for WWW-Authenticate. In the browser, it's under Response Headers in DevTools → Network.
curl -sI https://example.com/ | grep -i '^www-authenticate:'
To compare response headers across many URLs at once, use the HTTP Status Checker.
Frequently asked questions
Is WWW-Authenticate required on a 401?
The HTTP specification requires it. Many JSON APIs leave it out, which works in practice, but sending it tells clients how to fix the request.