1 files changed, 67 insertions, 0 deletions
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`.
+