From 56e16e29db55dae84549229d24b971f8bcf7da21 Mon Sep 17 00:00:00 2001
From: Owen Jacobson <owen@grimoire.ca>
Date: Wed, 16 Oct 2024 01:30:44 -0400
Subject: 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`.
---
 docs/api/initial-setup.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 docs/api/initial-setup.md

(limited to 'docs/api/initial-setup.md')

diff --git a/docs/api/initial-setup.md b/docs/api/initial-setup.md
new file mode 100644
index 0000000..ad57089
--- /dev/null
+++ b/docs/api/initial-setup.md
@@ -0,0 +1,67 @@
+# Initial setup
+
+```mermaid
+---
+Service lifecycle
+---
+stateDiagram-v2
+	uninit : Awaiting setup
+	inservice : In service
+
+	[*] --> uninit
+	uninit --> inservice : POST /api/setup
+	inservice --> [*]
+```
+
+New instances of this service require an initial setup step before they can fully enter service. This setup is performed online, via the API endpoints in this section.
+
+
+## Requests before setup completed
+
+Before the service is set up, all API endpoints, other than those specifically documented as exceptions, will return a status of `503 Service Unavailable` to all requests.
+
+Initial setup can be completed only once.
+
+
+## `POST /api/setup`
+
+Initial setup performs the following tasks:
+
+* Create the first login for the service.
+
+	This is the only login that does not require an [invitation](./invitations.md).
+
+**This endpoint does not require an `identity` cookie.**
+
+**This endpoint can be called before initial setup.**
+
+### Request
+
+```json
+{
+	"name": "example username",
+	"password": "the plaintext password",
+}
+```
+
+The request must have the following fields:
+
+| Field      | Type   | Description |
+|:-----------|:-------|:--|
+| `name`     | string | The initial login's name. |
+| `password` | string | The initial 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 initial login created for this request. See the [authentication](./authentication) section for details on how this cookie may be used.
+
+The cookie will expire if it is not used regularly.
+
+### Setup previously completed
+
+Once completed, this operation cannot be performed a second time. Subsequent requests to this endpoint will respond with a status of `409 Conflict`.
+
-- 
cgit v1.2.3