From 812f1cafe3f8a68bf45b677fade7417c30d92eac Mon Sep 17 00:00:00 2001
From: Owen Jacobson <owen@grimoire.ca>
Date: Fri, 11 Oct 2024 22:40:03 -0400
Subject: Create APIs for inviting users.

---
 docs/api.md | 76 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 75 insertions(+), 1 deletion(-)

(limited to 'docs/api.md')

diff --git a/docs/api.md b/docs/api.md
index 3545a46..f91780e 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -88,7 +88,7 @@ If the token is not valid or has expired, then `hi` will send back a 401 Unautho
 
 ### `POST /api/auth/login`
 
-Authenticates the user by login name and password, creating a login if none exists. **This endpoint does not require an `identity` cookie.**
+Authenticates the user by login name and password. **This endpoint does not require an `identity` cookie.**
 
 #### Request
 
@@ -123,6 +123,80 @@ Invalidates the identity token, logging the user out.
 
 This endpoint returns a 204 No Content response on success, with a `Set-Cookie` header that clears the `identity` cookie. The cookie provided in the request is also invalidated, and will not authenticate future requests even if the client fails to process the `Set-Cookie` response header.
 
+## Invitations
+
+Other than the login created during initial setup, new logins can only be created by accepting _invitations_. An invitation can be used at most once, and expires after a day; to invite multiple people, create multiple invitations.
+
+### `POST /api/invite`
+
+Creates an invitation.
+
+#### Request
+
+```json
+{}
+```
+
+#### On success
+
+This endpoint returns a new invitation each time it's called:
+
+```json
+{
+    "id": "I3884",
+    "issuer": "Labcd1234",
+    "issued_at": "2024-10-12T01:43:12.001853Z"
+}
+```
+
+### `GET /api/invite/:invite`
+
+Returns information about a previously-created invite. **This endpoint does not require an `identity` cookie.**
+
+The `:invite` placeholder must be an invite ID, as returned by `POST /api/invite`.
+
+#### On success
+
+This endpoint returns the existing invitation:
+
+```json
+{
+    "issuer": {
+        "id": "Labcd1234",
+        "name": "i send you invites"
+    },
+    "issued_at": "2024-10-12T01:43:12.001853Z"
+}
+```
+
+#### Invite not found
+
+This endpoint returns a 404 Not Found response if the invite ID in the path does not exist, or has already been accepted.
+
+
+### `POST /api/invite/:invite`
+
+Accepts an invitation and creates a new login. **This endpoint does not require an `identity` cookie.**
+
+The `:invite` placeholder must be an invite ID, as returned by `POST /api/invite`.
+
+#### Request
+
+```json
+{
+    "name": "example login",
+    "password": "correct-horse-battery-staple"
+}
+```
+
+#### On success
+
+This endpoint returns a 204 No Content response on success, with a `Set-Cookie` header setting the `identity` cookie to a newly created token for this login. See the [Authentication](#Authentication) section for the details of this cookie. The invite is consumed, and cannot be accepted a second time.
+
+#### Invite not found
+
+This endpoint returns a 404 Not Found response if the invite ID in the path does not exist, or has already been accepted.
+
 ## Working with channels
 
 Channels are the containers for conversations. The API supports listing channels, creating new channels, and send messages to an existing channel.
-- 
cgit v1.2.3