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, 157 insertions, 0 deletions

diff --git a/docs/api/invitations.md b/docs/api/invitations.md
new file mode 100644
index 0000000..0f21a0e
--- /dev/null
+++ b/docs/api/invitations.md
@@ -0,0 +1,157 @@
+# Invitations
+
+```mermaid
+---
+Invitation
+---
+sequenceDiagram
+	actor Andrea
+	participant API
+	actor Blake
+
+	Andrea ->>+ API : POST /api/invite
+	API -->>- Andrea : Invitation: "Iabcd1234"
+
+	Andrea --) Blake : https://example.net/invite/Iabcd1234
+
+	Blake ->>+ API : GET /api/invite/Iabcd1234
+	API -->>- Blake : Invited by Andrea
+
+	Blake ->>+ API : POST /api/invite/Iabcd1234
+	API -->>- Blake : Success
+```
+
+Other than the login created during [initial setup](./initial-setup.md), new logins can only be created by using invitations.
+
+Any login can create invitations. Each invitation can be accepted at most once. An invitation which is not accepted within 24 hours expires.
+
+
+## `POST /api/invite`
+
+Creates an invitation.
+
+### Request
+
+```json
+{}
+```
+
+The request must be an empty JSON object.
+
+### Success
+
+This endpoint will respond with a status of `200 Okay` when successful. The body of the response will be a JSON object describing the new invitation:
+
+```json
+{
+	"id": "I3884",
+	"issuer": "Labcd1234",
+	"issued_at": "2024-10-12T01:43:12.001853Z"
+}
+```
+
+The response will include the following fields:
+
+| Field       | Type   | Description |
+|:------------|:-------|:--|
+| `id`        | string | A unique identifier for the invitation. This ID must be given to the invitee. |
+| `issuer`    | string | The login ID of the invitation's issuer. |
+| `issued_at` | string | The timestamp from which the invitation will expire. |
+
+Clients and their operators are responsible for delivering the invitation to the invitee. Clients are strongly recommended to construct a URL for the invitation so that the invitee can take action on it easily. The included client supports URLs of the format `https://example.net/invite/:id` (with the `:id` placeholder substituted with the invitation's ID).
+
+
+## `GET /api/invite/:id`
+
+Returns information about an outstanding invitation.
+
+This endpoint requires the following path parameter:
+
+| Parameter | Type   | Description |
+|:----------|:-------|:--|
+| `id`      | string |  An invitation ID, as returned from a previous request to `POST /api/invite`. |
+
+**This endpoint does not require an `identity` cookie.**
+
+### On success
+
+This endpoint will respond with a status of `200 Okay` when successful. The body of the response will be a JSON object describing the invitation:
+
+```json
+{
+	"issuer": {
+		"id": "Labcd1234",
+		"name": "i send you invites"
+	},
+	"issued_at": "2024-10-12T01:43:12.001853Z"
+}
+```
+
+The response will include the following fields:
+
+| Field       | Type   | Description |
+|:------------|:-------|:--|
+| `issuer`    | object | The details of the login that issued the invitation. |
+| `issued_at` | string | The timestamp from which the invitation will expire. |
+
+The `issuer` object will include the following fields:
+
+| Field  | Type   | Description |
+|:-------|:-------|:--|
+| `id`   | string | The login ID of the invitation's issuer. |
+| `name` | string | The login name of the invitation's issuer. |
+
+Clients should present the issuer's name to the user when presenting an invitation, so as to personalize the invitation and help them understand their connection with the service.
+
+### Invitation not found
+
+This endpoint will respond with a status of `404 Not Found` when the invitation ID either does not exist, or has already been accepted.
+
+
+## `POST /api/invite/:id`
+
+Accepts an invitation and creates a new login.
+
+This endpoint requires the following path parameter:
+
+| Parameter | Type   | Description |
+|:----------|:-------|:--|
+| `id`      | string |  An invitation ID, as returned from a previous request to `POST /api/invite`. |
+
+**This endpoint does not require an `identity` cookie.**
+
+### Request
+
+```json
+{
+	"name": "example login",
+	"password": "correct-horse-battery-staple"
+}
+```
+
+The request must have the following fields:
+
+| Field      | Type   | Description |
+|:-----------|:-------|:--|
+| `name`     | string | The new login's name. |
+| `password` | string | The new login's password, in plain text. |
+
+### Success
+
+<!-- This prose is duplicated from authentication.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 created for this request. See the [authentication](./authentication.md) section for details on how this cookie may be used.
+
+The cookie will expire if it is not used regularly.
+
+### Invitation not found
+
+This endpoint will respond with a status of `404 Not Found` when the invitation ID either does not exist, or has already been accepted.
+
+### Name in use
+
+This endpoint will respond with a status of `409 Conflict` if the requested login name has already been taken.
+
+The invitation can be accepted with a different name.