diff options
Diffstat (limited to 'docs/api/invitations.md')
| -rw-r--r-- | docs/api/invitations.md | 39 |
1 files changed, 7 insertions, 32 deletions
diff --git a/docs/api/invitations.md b/docs/api/invitations.md index 04e92c8..9b86b9e 100644 --- a/docs/api/invitations.md +++ b/docs/api/invitations.md @@ -39,8 +39,7 @@ 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: +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 { @@ -58,8 +57,7 @@ The response will include the following fields: | `issuer` | string | The user 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). +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` @@ -75,8 +73,7 @@ This endpoint requires the following path parameter: ### 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: +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 { @@ -96,13 +93,11 @@ The response will include the following fields: | `issuer` | string | The name of the invitation's issuer. | | `issued_at` | string | The timestamp from which the invitation will expire. | -Clients should present the -`issuer` to the user when presenting an invitation, so as to personalize the invitation and help them understand their connection with the service. +Clients should present the `issuer` 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. +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` @@ -146,29 +141,9 @@ The proposed `name` must be valid. The precise definition of valid is still up i <!-- 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 -`200 Okay` when successful. The body of the response will be a JSON object describing the newly-created user: - -```json -{ - "id": "Uabcd1234", - "name": "Andrea" -} -``` - -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. | - -The returned name may not be identical to the name requested, as the name will be converted to [normalization form C](http://www.unicode.org/reports/tr15/) automatically. The returned name will include this normalization; the service will use the normalized name elsewhere, and does not store the originally requested name. - -The provided password will also be converted to normalization form C. However, the normalized password is not returned to the client. +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 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. |