1 files changed, 18 insertions, 0 deletions
diff --git a/docs/api.md b/docs/api.md
index 803e457..e380c95 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -28,6 +28,7 @@ curl -u alice:secret -X POST 'localhost:3000/store/stats/visits?increment=1'  #
   removes the maps it leaves empty), and `POST` inserts into a list at an index, the
   items from there moving up, or with `?increment=n` adds `n` to a counter (Concurrent
   writes), or with `?cast=<type>` casts what is there to another type (Types).
+  `?signed=true` on any of them has the node sign the change (Signed changes).
 * 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.
@@ -241,6 +242,23 @@ touched what is at `settings`.
 Every node holds every change, so user names are known to the whole swarm, and so is
 who wrote what, until a remake drops the history ([`remakes.md`](remakes.md)).
 
+## Signed changes
+
+Every node signs changes it commits with its node key: an Ed25519 signature over the
+change's hash, kept beside the document. One signature vouches for more than its
+change: a node's change builds on its previous one, and a change's hash covers what it
+builds on, so a signed change vouches for all the node's changes before it. So not
+every change is signed, only those that
+
+* touch protocol data (`_continuum`),
+* touch a path listed in `_continuum/access/signed` (within it, or above it), a list
+  of paths, each a list of segments as capabilities name them
+  ([`access.md`](access.md)): `[["config"], ["servers", "eu"]]`,
+* or were written with `?signed=true`.
+
+A change left unsigned, such as a metric written many times a second, is vouched for
+by the node's next signed one.
+
 ## Protocol data
 
 `_continuum` holds what the nodes coordinate through: the swarm ID, the member registry,