API docs rewrite.

Having the whole API in a single file was starting to feel very cramped and constraining. This rewrite breaks it out into sections; as a side effect, the docs are now about 2.5x as long as they were, as the rewrite allows more space for each idea without crowding the page.

The docs are best read by running `tools/docs-api`.

1 files changed, 86 insertions, 0 deletions

diff --git a/docs/api/authentication.md b/docs/api/authentication.md
new file mode 100644
index 0000000..d4c1f70
--- /dev/null
+++ b/docs/api/authentication.md
@@ -0,0 +1,86 @@
+# Authentication
+
+```mermaid
+---
+Authentication states
+---
+stateDiagram-v2
+	[*] --> Unauthenticated
+	Unauthenticated --> Authenticated : /api/auth/login
+	Authenticated --> Unauthenticated : /api/auth/logout
+	Authenticated --> Unauthenticated : Token expired
+```
+
+Authentication associates each authenticated request with a login.
+
+
+## Identity tokens
+
+A login is primarily authenticated using its username and password. However, passwords are a sensitive, long-lived credential, and are also operationally expensive to verify; for routine access, requests are authenticated using an identity token, instead.
+
+Tokens are issued by logging into the service, using the `/api/auth/login` endpoint. The `/api/auth/logout` endpoint immediately invalidates the token used to make a request to it. Tokens are also invalidated after seven days of inactivity.
+
+To authenticate a request, include  `cookie: identity=TOKEN SECRET` header in the request. For browser-based clients, this may happen automatically.
+
+
+## Authentication failures
+
+Unless the endpoint's documentation says otherwise, all endpoints require authentication. Making a request to any endpoint that requires authentication, either without a token, or with a token that is not valid or that has expired, causes the service to return a `401 Unauthorized` response, instead of the responses documented for the endpoint the request was intended for. The API will not take action on requests that fail authentication in this way.
+
+
+## `POST /api/auth/login`
+
+Authenticates the user using their login name and password. The login must exist before calling this endpoint.
+
+To create logins, see [initial setup](./initial-setup.md) and [invitations](./invitations.md).
+
+**This endpoint does not require an `identity` cookie.**
+
+### Request
+
+```json
+{
+	"name": "example username",
+	"password": "the plaintext password",
+}
+```
+
+The request must have the following fields:
+
+| Field      | Type   | Description |
+|:-----------|:-------|:--|
+| `name`     | string | The login's name. |
+| `password` | string | The login's password, in plain text. |
+
+### Success
+
+<!-- This prose is duplicated by 03-initial-setup.md and in 04-invitations.md, with small changes for context. If you edit it here, edit it there, too. -->
+
+This endpoint will respond with a status of `204 No Content` when successful.
+
+The response will include a `Set-Cookie` header for the `identity` cookie, providing the client with a newly-minted identity token associated with the login identified in the request. This token's value must be kept confidential.
+
+The cookie will expire if it is not used regularly.
+
+### Authentication failure
+
+This endpoint will respond with a status of `401 Unauthorized` if the login name and password do not correspond to an existing login.
+
+
+## `POST /api/auth/logout`
+
+Invalidates the identity token used to make the request, logging the user out.
+
+### Request
+
+```json
+{}
+```
+
+The request must be an empty JSON object.
+
+### Success
+
+This endpoint will respond with a status of `204 No Content` when successful.
+
+The response will include a `Set-Cookie` header that clears the `identity` cookie. Regardless of whether the client clears the cookie, the service also invalidates the token.