diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api/authentication.md | 53 | ||||
| -rw-r--r-- | docs/api/initial-setup.md | 27 | ||||
| -rw-r--r-- | docs/api/invitations.md | 39 |
3 files changed, 21 insertions, 98 deletions
diff --git a/docs/api/authentication.md b/docs/api/authentication.md index fbd5959..189103e 100644 --- a/docs/api/authentication.md +++ b/docs/api/authentication.md @@ -71,32 +71,15 @@ The request must have the following fields: <!-- 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 -`200 Okay` when successful. The body of the response will be a JSON object describing the authenticated user: - -```json -{ - "id": "Uabcd1234", - "name": "Andrea" -} -``` - -The response will include the following fields: - -| Field | Type | Description | -| :----- | :----- | :----------------------------- | -| `id` | string | The authenticated user's ID. | -| `name` | string | The authenticated user's name. | +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 user identified in the request. This token's value must be kept confidential. +The response will include a `Set-Cookie` header for the `identity` cookie, providing the client with a newly-minted identity token associated with the user 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 user. +This endpoint will respond with a status of `401 Unauthorized` if the login name and password do not correspond to an existing user. ## `POST /api/auth/logout` @@ -114,13 +97,16 @@ The request must be an empty JSON object. 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. +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. ## `POST /api/password` Changes the current user's password, and invalidates all outstanding identity tokens. +### Authentication failure + +This endpoint will respond with a status of `401 Unauthorized` if the provided identity token is not valid. + ### Request ```json @@ -139,29 +125,12 @@ The request must have the following fields: ### 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 authenticated user: - -```json -{ - "id": "Uabcd1234", - "name": "Andrea" -} -``` - -The response will include the following fields: - -| Field | Type | Description | -| :----- | :----- | :----------------------------- | -| `id` | string | The authenticated user's ID. | -| `name` | string | The authenticated user's name. | +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. All previously-created identity cookies will cease to be valid. +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. All previously-created identity cookies will cease to be valid. The cookie will expire if it is not used regularly. ### Authentication failure -This endpoint will respond with a status of `400 Bad Request` if the -`password` does not match the login's current password. +This endpoint will respond with a status of `400 Bad Request` if the `password` does not match the login's current password. diff --git a/docs/api/initial-setup.md b/docs/api/initial-setup.md index a3f6506..b52771f 100644 --- a/docs/api/initial-setup.md +++ b/docs/api/initial-setup.md @@ -17,8 +17,7 @@ New instances of this service require an initial setup step before they can full ## Requests before setup completed -Before the service is set up, all API endpoints, other than those specifically documented as exceptions, will return a status of -`503 Service Unavailable` to all requests. +Before the service is set up, all API endpoints, other than those specifically documented as exceptions, will return a status of `503 Service Unavailable` to all requests. Initial setup can be completed only once. @@ -64,29 +63,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: +This endpoint will respond with a status of `204 No Content` when successful. -```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. - -The response will include a `Set-Cookie` header for the -`identity` cookie, providing the client with a newly-minted identity token associated with the initial user created for this request. See the [authentication](./authentication) 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 initial user created for this request. See the [authentication](./authentication) section for details on how this cookie may be used. The cookie will expire if it is not used regularly. 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. |