diff options
Diffstat (limited to 'docs/api/invitations.md')
| -rw-r--r-- | docs/api/invitations.md | 26 |
1 files changed, 12 insertions, 14 deletions
diff --git a/docs/api/invitations.md b/docs/api/invitations.md index 0be2c2e..04e92c8 100644 --- a/docs/api/invitations.md +++ b/docs/api/invitations.md @@ -25,7 +25,6 @@ Other than the user created during [initial setup](./initial-setup.md), new user Any user 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. @@ -54,7 +53,7 @@ This endpoint will respond with a status of 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 user ID of the invitation's issuer. | | `issued_at` | string | The timestamp from which the invitation will expire. | @@ -62,7 +61,6 @@ The response will include the following fields: 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. @@ -70,7 +68,7 @@ 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.** @@ -93,7 +91,7 @@ This endpoint will respond with a status of The response will include the following fields: | Field | Type | Description | -|:------------|:-------|:-----------------------------------------------------| +| :---------- | :----- | :--------------------------------------------------- | | `id` | string | The ID of the invitation. | | `issuer` | string | The name of the invitation's issuer. | | `issued_at` | string | The timestamp from which the invitation will expire. | @@ -106,7 +104,6 @@ Clients should present the 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 user. @@ -114,7 +111,7 @@ Accepts an invitation and creates a new user. 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.** @@ -131,18 +128,19 @@ This endpoint requires the following path parameter: The request must have the following fields: | Field | Type | Description | -|:-----------|:-------|:----------------------------------------| +| :--------- | :----- | :-------------------------------------- | | `name` | string | The new user's name. | | `password` | string | The new user's password, in plain text. | <!-- Reproduced in initial-setup.md. Edit in both places. --> + The proposed `name` must be valid. The precise definition of valid is still up in the air, but, at minimum: -* It must be non-empty. -* It must not be "too long." (Currently, 64 characters is too long.) -* It must begin with a printing character. -* It must end with a printing character. -* It must not contain runs of multiple whitespace characters. +- It must be non-empty. +- It must not be "too long." (Currently, 64 characters is too long.) +- It must begin with a printing character. +- It must end with a printing character. +- It must not contain runs of multiple whitespace characters. ### Success @@ -161,7 +159,7 @@ This endpoint will respond with a status of The response will include the following fields: | Field | Type | Description | -|:-------|:-------|:---------------------------------------------------------------------------------------------------------------------------------------------------| +| :----- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | A unique identifier for the newly-created user. This can be used to associate the user with other events, or to make API calls targeting the user. | | `name` | string | The user's name. | |