Update the API docs to describe `user`s, not `login`s.

1 files changed, 53 insertions, 44 deletions

diff --git a/docs/api/authentication.md b/docs/api/authentication.md
index 93a8e52..7b5ebd7 100644
--- a/docs/api/authentication.md
+++ b/docs/api/authentication.md
@@ -11,43 +11,45 @@ stateDiagram-v2
 	Authenticated --> Unauthenticated : Token expired
 ```
 
-Authentication associates each authenticated request with a login.
+Authentication associates each authenticated request with a user.
 
-To create logins, see [initial setup](./initial-setup.md) and [invitations](./invitations.md).
+To create users, see [initial setup](./initial-setup.md) and [invitations](./invitations.md).
 
 
 ## Names
 
 <!-- This prose is duplicated in channels-messages.md. If you change it here, consider changing it there, too. -->
-The service handles login names using two separate forms.
+The service handles user names using two separate forms.
 
-The first form is as given in the request used to create the login. This form of the login name is used throughout the API, and the service will preserve the name as entered (other than applying normalization), so that users' preferences around capitalization and accent marks are preserved.
+The first form is as given in the request used to create the user. This form of the use name is used throughout the API, and the service will preserve the name as entered (other than applying normalization), so that users' preferences around capitalization and accent marks are preserved.
 
-The second form is a "canonical" form, used internally by the service to control uniqueness and match names to logins. The canonical form is both case-folded and normalized.
+The second form is a "canonical" form, used internally by the service to control uniqueness and match names to users. The canonical form is both case-folded and normalized.
 
 The canonical form is not available to API clients, but its use has practical consequences:
 
-* Names that differ only by case or only by code point sequence are treated as the same name. If the name is in use, changing the capitalization or changing the sequence of combining marks will not allow the creation of a second "identical" login.
-* The login API accepts any name that canonicalizes to the form stored in the database, making login names effectively case-insensitive.
-
+* Names that differ only by case or only by code point sequence are treated as the same name. If the name is in use, changing the capitalization or changing the sequence of combining marks will not allow the creation of a second "identical" user.
+* The login API accepts any name that canonicalizes to the form stored in the database, making user names effectively case-insensitive and composition-insensitive.
 
 ## Identity tokens
 
-A login is primarily authenticated using its username and password. However, passwords are a sensitive, long-lived credential, and are also operationally expensive to verify; for routine access, requests are authenticated using an identity token, instead.
+A user is primarily authenticated using its username and password. However, passwords are a sensitive, long-lived credential, and are also operationally expensive to verify; for routine access, requests are authenticated using an identity token, instead.
 
-Tokens are issued by logging into the service, using the `/api/auth/login` endpoint. The `/api/auth/logout` endpoint immediately invalidates the token used to make a request to it. Tokens are also invalidated after seven days of inactivity.
+Tokens are issued by logging into the service, using the `/api/auth/login` endpoint. The
+`/api/auth/logout` endpoint immediately invalidates the token used to make a request to it. Tokens are also invalidated after seven days of inactivity.
 
-To authenticate a request, include  `cookie: identity=TOKEN SECRET` header in the request. For browser-based clients, this may happen automatically.
+To authenticate a request, include
+`cookie: identity=TOKEN SECRET` header in the request. For browser-based clients, this may happen automatically.
 
 
 ## Authentication failures
 
-Unless the endpoint's documentation says otherwise, all endpoints require authentication. Making a request to any endpoint that requires authentication, either without a token, or with a token that is not valid or that has expired, causes the service to return a `401 Unauthorized` response, instead of the responses documented for the endpoint the request was intended for. The API will not take action on requests that fail authentication in this way.
+Unless the endpoint's documentation says otherwise, all endpoints require authentication. Making a request to any endpoint that requires authentication, either without a token, or with a token that is not valid or that has expired, causes the service to return a
+`401 Unauthorized` response, instead of the responses documented for the endpoint the request was intended for. The API will not take action on requests that fail authentication in this way.
 
 
 ## `POST /api/auth/login`
 
-Authenticates the user using their login name and password. The login must exist before calling this endpoint.
+Authenticates the user using their name and password. The user must exist before calling this endpoint.
 
 **This endpoint does not require an `identity` cookie.**
 
@@ -55,50 +57,53 @@ Authenticates the user using their login name and password. The login must exist
 
 ```json
 {
-	"name": "example username",
-	"password": "the plaintext password",
+  "name": "example username",
+  "password": "the plaintext password"
 }
 ```
 
 The request must have the following fields:
 
-| Field      | Type   | Description |
-|:-----------|:-------|:--|
-| `name`     | string | The login's name. |
+| Field      | Type   | Description                          |
+|:-----------|:-------|:-------------------------------------|
+| `name`     | string | The login's name.                    |
 | `password` | string | The login's password, in plain text. |
 
 ### Success
 
 <!-- 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 login:
+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": "Labcd1234",
-	"name": "Andrea"
+  "id": "Uabcd1234",
+  "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. |
+| Field  | Type   | Description                    |
+|:-------|:-------|:-------------------------------|
+| `id`   | string | The authenticated user's ID.   |
+| `name` | string | The authenticated user'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.
+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 login.
+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`
 
-Invalidates the identity token used to make the request, logging the user out.
+Invalidates the identity token used to make the request, logging the caller out.
 
 ### Request
 
@@ -112,51 +117,55 @@ 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 login's password, and invalidate all outstanding identity tokens.
+Changes the current user's password, and invalidates all outstanding identity tokens.
 
 ### Request
 
 ```json
 {
-	"password": "my-old-password",
-	"to": "my-new-password"
+  "password": "my-old-password",
+  "to": "my-new-password"
 }
 ```
 
 The request must have the following fields:
 
-| Field      | Type   | Description |
-|:-----------|:-------|:--|
+| Field      | Type   | Description                                    |
+|:-----------|:-------|:-----------------------------------------------|
 | `password` | string | The login's _current_ password, in plain text. |
-| `to`       | string | The login's _new_ 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:
+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": "Labcd1234",
-	"name": "Andrea"
+  "id": "Uabcd1234",
+  "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. |
+| Field  | Type   | Description                    |
+|:-------|:-------|:-------------------------------|
+| `id`   | string | The authenticated user's ID.   |
+| `name` | string | The authenticated user'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 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.