2 files changed, 15 insertions, 3 deletions
diff --git a/docs/access.md b/docs/access.md
index 909d915..3541efd 100644
--- a/docs/access.md
+++ b/docs/access.md
@@ -125,9 +125,11 @@ jq -n --arg c "$c" --rawfile s sig '{user: "alice", challenge: $c, signature: $s
   curl -s -X POST localhost:3000/auth/login/key -H 'Content-Type: application/json' -d @-
 ```
 
-A challenge is the node's, signed by it, valid for five minutes, and taken once (the
-node remembers which in memory: after a restart, one captured in its five minutes
-could be taken once more; it goes over TLS, as passwords do);
+A challenge is the node's, signed by it, valid for five minutes (`--challenge-lifetime`),
+and taken once (the node remembers which in memory: after a restart, one captured in
+its five minutes could be taken once more; it goes over TLS, as passwords do). A user
+logs in by key at most 100 times on a node within those minutes
+(`--key-logins-per-user`), so one holding a key can't keep the others out;
 the signature must be by one of the user's keys, as the registry the node holds then
 says, and the user enabled (`401` if not, saying why). A swarm without a registry has
 no keys (`409`).
diff --git a/docs/example.toml b/docs/example.toml
index d2d9a67..cce8780 100644
--- a/docs/example.toml
+++ b/docs/example.toml
@@ -95,6 +95,16 @@ htpasswd = "/etc/continuum/htpasswd"
 # logs in again.
 # session-lifetime = "7d"
 
+# How long a challenge to log in by key (POST /auth/challenge) is valid: the node
+# remembers each used until then, and counts a user's logins by key over it
+# (key-logins-per-user).
+# challenge-lifetime = "5m"
+
+# Logins by key a user may make on this node within a challenge's lifetime
+# (challenge-lifetime); past it, that user waits, others don't. 10 000 by all users
+# together at most.
+# key-logins-per-user = 100
+
 # Where the reverse proxies whose user-header is believed connect from: IP addresses (or
 # ranges, as ADDRESS/BITS), and unix for the API's Unix sockets (bind-addr). On a host
 # with other users, leave out the addresses and have the proxy use a Unix socket: others