diff options
Diffstat (limited to 'docs/api/invitations.md')
| -rw-r--r-- | docs/api/invitations.md | 157 |
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. |