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.