docs: basic authentication sends the password unasked

Review 4, 1269's note: the node challenges for a password (`WWW-Authenticate`) only
what isn't a browser, by `Sec-Fetch-*` or a `Mozilla/…` user agent. A client calling
itself Mozilla that waits for a challenge before sending its password would get none:
api.md says to send the password with the request, as `curl -u` does, and why.

1 files changed, 4 insertions, 1 deletions

diff --git a/docs/api.md b/docs/api.md
index 078594b..3fb99be 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -32,7 +32,10 @@ curl -u alice:secret -X POST 'localhost:3000/store/stats/visits?increment=1'  #
 * Bodies are JSON (`application/json`, the default), text (`text/plain`, stored as a
   string), or a value of a type of its own (Types); answers are JSON, or as `Accept`
   asks. Numbers in JSON are stored as integers where they fit, as floats otherwise.
-* Every request needs a user from the node's `--htpasswd` (basic authentication),
+* Every request needs a user from the node's `--htpasswd` (basic authentication: send
+  the password with the request, as `curl -u` does; the node asks for one with a
+  `401`'s `WWW-Authenticate` only of what isn't a browser, by its `Sec-Fetch-*`
+  headers or a `Mozilla/…` user agent, so a browser never prompts),
   named by a reverse proxy in front that authenticated it (`--user-header`;
   [`operations.md`](operations.md), Behind a reverse proxy), or a token from logging in on any node
   of the swarm (`Authorization: Bearer`, [`access.md`](access.md), Tokens). What each may do, the swarm's user