1 files changed, 47 insertions, 0 deletions
diff --git a/docs/api/authentication.md b/docs/api/authentication.md
index 135e91b..93a8e52 100644
--- a/docs/api/authentication.md
+++ b/docs/api/authentication.md
@@ -113,3 +113,50 @@ 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.
+
+
+## `POST /api/password`
+
+Changes the current login's password, and invalidate all outstanding identity tokens.
+
+### Request
+
+```json
+{
+	"password": "my-old-password",
+	"to": "my-new-password"
+}
+```
+
+The request must have the following fields:
+
+| Field      | Type   | Description |
+|:-----------|:-------|:--|
+| `password` | string | The login's _current_ password, in plain text. |
+| `to`       | string | The login's _new_ password, in plain text. |
+
+### 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 login:
+
+```json
+{
+	"id": "Labcd1234",
+	"name": "Andrea"
+}
+```
+
+The response will include the following fields:
+
+| Field       | Type   | Description |
+|:------------|:-------|:--|
+| `id`        | string | The authenticated login's ID. |
+| `name`      | string | The authenticated login's name. |
+
+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.