5 files changed, 96 insertions, 3 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.
diff --git a/docs/api/channels-messages.md b/docs/api/channels-messages.md
index 9854d22..2aa8ac5 100644
--- a/docs/api/channels-messages.md
+++ b/docs/api/channels-messages.md
@@ -64,6 +64,14 @@ The request must have the following fields:
 |:-------|:-------|:--|
 | `name` | string | The channel's name. |
 
+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.
+
 ### Success
 
 This endpoint will respond with a status of `202 Accepted` when successful. The body of the response will be a JSON object describing the new channel:
@@ -86,7 +94,11 @@ The returned name may not be identical to the name requested, as the name will b
 
 When completed, the service will emit a [channel created](events.md#channel-created) event with the channel's ID.
 
-### Duplicate channel name
+### Name not valid
+
+This endpoint will respond with a status of `400 Bad Request` if the proposed `name` is not valid.
+
+### Channel name in use
 
 This endpoint will respond with a status of `409 Conflict` if a channel with the requested name already exists.
 
@@ -152,7 +164,7 @@ This endpoint will respond with a status of `404 Not Found` if the channel ID is
 
 Deletes a channel.
 
-Deleting a channel prevents it from receiving any further messages, and deletes the messages it contains at that point.
+Deleting a channel prevents it from receiving any further messages. The channel must be empty; to delete a channel with messages in it, delete the messages first (or wait for them to expire).
 
 This endpoint requires the following path parameter:
 
@@ -178,6 +190,9 @@ The response will have the following fields:
 
 When completed, the service will emit a [message deleted](events.md#message-deleted) event for each message in the channel, followed by a [channel deleted](events.md#channel-deleted) event with the channel's ID.
 
+### Channel not empty
+
+This endpoint will respond with a status of `409 Conflict` if the channel contains messages.
 
 ### Invalid channel ID
 
@@ -215,3 +230,7 @@ When completed, the service will emit a [message deleted](events.md#message-dele
 ### Invalid message ID
 
 This endpoint will respond with a status of `404 Not Found` if the message ID is not valid.
+
+### Not the sender
+
+This endpoint will respond with a status of `403 Forbidden` if the message was sent by a different login.
diff --git a/docs/api/events.md b/docs/api/events.md
index b08e971..b23469c 100644
--- a/docs/api/events.md
+++ b/docs/api/events.md
@@ -46,7 +46,7 @@ This endpoint is designed for use with the [EventSource] DOM API, and supports s
 
 ### Query parameters
 
-This endpoint accepts an optional `resume_point` (integer) query parameter. When provided, the event stream will include events published after that point in time; the value must be the value obtained by calling the [`GET /api/boot`](./boot.md) method. If absent, the returned event stream includes all events.
+This endpoint requires a `resume_point` (integer) query parameter. The event stream will collect events published after that point in time. The value must be obtained by calling the [`GET /api/boot`](./boot.md) method.
 
 ### Request headers
 
diff --git a/docs/api/initial-setup.md b/docs/api/initial-setup.md
index 306d798..c2bdaec 100644
--- a/docs/api/initial-setup.md
+++ b/docs/api/initial-setup.md
@@ -51,6 +51,16 @@ The request must have the following fields:
 | `name`     | string | The initial login's name. |
 | `password` | string | The initial login's password, in plain text. |
 
+<!-- Reproduced in invitations.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.
+
 ### Success
 
 <!-- This prose is duplicated from authentication.md, with small changes for context. If you edit it here, edit it there, too. -->
@@ -79,6 +89,10 @@ The response will include a `Set-Cookie` header for the `identity` cookie, provi
 
 The cookie will expire if it is not used regularly.
 
+### Name not valid
+
+This endpoint will respond with a status of `400 Bad Request` if the proposed `name` is not valid.
+
 ### Setup previously completed
 
 Once completed, this operation cannot be performed a second time. Subsequent requests to this endpoint will respond with a status of `409 Conflict`.
diff --git a/docs/api/invitations.md b/docs/api/invitations.md
index ddbef8a..1839ef5 100644
--- a/docs/api/invitations.md
+++ b/docs/api/invitations.md
@@ -130,6 +130,15 @@ The request must have the following fields:
 | `name`     | string | The new login's name. |
 | `password` | string | The new login'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.
+
 ### Success
 
 <!-- This prose is duplicated from authentication.md, with small changes for context. If you edit it here, edit it there, too. -->
@@ -162,6 +171,10 @@ The cookie will expire if it is not used regularly.
 
 This endpoint will respond with a status of `404 Not Found` when the invitation ID either does not exist, or has already been accepted.
 
+### Name not valid
+
+This endpoint will respond with a status of `400 Bad Request` if the proposed `name` is not valid.
+
 ### Name in use
 
 This endpoint will respond with a status of `409 Conflict` if the requested login name has already been taken.