diff options
Diffstat (limited to 'docs/api/authentication.md')
| -rw-r--r-- | docs/api/authentication.md | 53 |
1 files changed, 11 insertions, 42 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. |