diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md
index d6e6293fd..dc53af719 100644
--- a/docs/api-guide/authentication.md
+++ b/docs/api-guide/authentication.md
@@ -84,7 +84,7 @@ When an unauthenticated request is denied permission there are two different err
 * [HTTP 401 Unauthorized][http401]
 * [HTTP 403 Permission Denied][http403]
 
-HTTP 401 responses must always include a `WWW-Authenticate` header, that instructs the client how to authenticate.  HTTP 403 responses do not include the `WWW-Authenticate` header.
+HTTP 401 responses must always include a `WWW-Authenticate` header, that instructs the client how to authenticate.  The `www_authenticate_behavior` setting controls how the header is generated: if set to `'first'` (the default), then only the text for the first scheme in the list will be used; if set to `'all'`, then a comma-separated list of the text for all the schemes will be used (see [MDN WWW-Authenticate](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/WWW-Authenticate) for more details).  HTTP 403 responses do not include the `WWW-Authenticate` header.
 
 The kind of response that will be used depends on the authentication scheme.  Although multiple authentication schemes may be in use, only one scheme may be used to determine the type of response.  **The first authentication class set on the view is used when determining the type of response**.
 
diff --git a/docs/api-guide/settings.md b/docs/api-guide/settings.md
index 47e2ce993..0c166227d 100644
--- a/docs/api-guide/settings.md
+++ b/docs/api-guide/settings.md
@@ -189,6 +189,13 @@ The class that should be used to initialize `request.auth` for unauthenticated r
 
 Default: `None`
 
+#### WWW_AUTHENTICATE_BEHAVIOR
+
+Determines whether a single or multiple challenges are presented in the `WWW-Authenticate` header.
+
+This should be set to `'first'` (the default value) or `'all'`. When set to `'first'`, the `WWW-Authenticate` header will be set to an appropriate challenge for the first authentication scheme in the list.
+When set to `'all'`, a comma-separated list of the challenge for all specified authentication schemes will be used instead (following the [syntax specification](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/WWW-Authenticate)).
+
 ---
 
 ## Test settings