apply suggestions from review, and other clarifications

content/client-server-api/_index.md

@@ -337,15 +337,15 @@ to prevent the access token being leaked in access/HTTP logs. The query
 string should only be used in cases where the `Authorization` header is
 inaccessible for the client.
 
-{{% changed-in v="1.3" %}} When credentials are required but missing or
+When credentials are required but missing or invalid, the HTTP call will
-invalid, the HTTP call will return with a status of 401 and the error code,
+return with a status of 401 and the error code, `M_MISSING_TOKEN` or
-`M_MISSING_TOKEN` or `M_UNKNOWN_TOKEN` respectively.  Note that an error code
+`M_UNKNOWN_TOKEN` respectively.  Note that an error code of `M_UNKNOWN_TOKEN`
-of `M_UNKNOWN_TOKEN` could mean one of four things:
+could mean one of four things:
 
 1. the access token was never valid.
 2. the access token has been logged out.
 3. the access token has been [soft logged out](#soft-logout).
-4. the access token [needs to be refreshed](#refreshing-access-tokens).
+4. {{< added-in v="1.3" >}} the access token [needs to be refreshed](#refreshing-access-tokens).
 
 When a client receives an error code of `M_UNKNOWN_TOKEN`, it should:
 
@@ -377,52 +377,56 @@ invalidate any access and refresh tokens previously assigned to that device.
 
 {{% added-in v="1.3" %}}
 
-Access tokens can expire after a certain amount of time. Any HTTP
+Access tokens can expire after a certain amount of time. Any HTTP calls that
-calls that use an expired access token will return with an error code
+use an expired access token will return with an error code `M_UNKNOWN_TOKEN`,
-`M_UNKNOWN_TOKEN`, preferably with `soft_logout: true`. When a client
+preferably with `soft_logout: true`. When a client receives this error and it
-receives this error and it has a refresh token, it should attempt to
+has a refresh token, it should attempt to refresh the access token by calling
-refresh the access token by calling `/refresh`. Clients can also
+[`/refresh`](#post_matrixclientv3refresh). Clients can also refresh their
-refresh their access token at any time, even if it has not yet
+access token at any time, even if it has not yet expired. If the token refresh
-expired. If the token refresh succeeds, it should use the new token
+succeeds, the client should use the new token for future requests, and can
-for future requests, and can re-try previously-failed requests with
+re-try previously-failed requests with the new token. When an access token is
-the new token. When an access token is refreshed, a new refresh token
+refreshed, a new refresh token may be returned; if a new refresh token is
-may be returned; if a new refresh token is given, the old refresh
+given, the old refresh token will be invalidated, and the new refresh token
-token will be invalidated, and the new refresh token should be used
+should be used when the access token needs to be refreshed.
-when the access token needs to be refreshed.
+
-
+The old refresh token remains valid until the new access token or refresh token
-If the token refresh fails, then the client can treat it as a [soft
+is used, at which point the old refresh token is revoked. This ensures that if
-logout](#soft-logout), if the error response included a `soft_logout:
+a client fails to receive or persist the new tokens, it will still be able to
-true` property, and attempt to obtain a new access token by re-logging
+refresh them.
-in. If the error response does not include a `soft_logout: true`
+
-property, the client should consider the user as being logged out.
+If the token refresh fails and the error response included a `soft_logout:
-
+true` property, then the client can treat it as a [soft logout](#soft-logout)
-Handling of clients that do not support refresh tokens is up to the
+and attempt to obtain a new access token by re-logging in. If the error
-homeserver; clients indicate their support for refresh tokens by
+response does not include a `soft_logout: true` property, the client should
-including a `refresh_token: true` property in the request body of the
+consider the user as being logged out.
-`/login` and `/register` endpoints. For example, homeservers may allow
+
-the use of non-expiring access tokens, or may expire access tokens
+Handling of clients that do not support refresh tokens is up to the homeserver;
-anyways and rely on soft logout behaviour on clients that don't
+clients indicate their support for refresh tokens by including a
-support refreshing.
+`refresh_token: true` property in the request body of the
+[`/login`](#post_matrixclientv3login) and
+[`/register`](#post_matrixclientv3register) endpoints. For example, homeservers
+may allow the use of non-expiring access tokens, or may expire access tokens
+anyways and rely on soft logout behaviour on clients that don't support
+refreshing.
 
 ### Soft logout
 
 A client can be in a "soft logout" state if the server requires
-re-authentication before continuing, but does not want to invalidate
+re-authentication before continuing, but does not want to invalidate the
-the client's session. That is, any persisted state held by the client,
+client's session. The server indicates that the client is in a soft logout
-such as encryption keys and device information, must not be reused and
+state by including a `soft_logout: true` parameter in an `M_UNKNOWN_TOKEN`
-must be discarded, and can be re-used if the client successfully
+error response; the `soft_logout` parameter defaults to `false`. If the
-re-authenticates.
+`soft_logout` parameter is omitted or is `false`, this means the server has
-
+destroyed the session and the client should not reuse it. That is, any
-The server indicates that the client is in a soft logout state by
+persisted state held by the client, such as encryption keys and device
-including a `soft_logout: true` parameter in an `M_UNKNOWN_TOKEN`
+information, must not be reused and must be discarded. If `soft_logout` is
-error response; the `soft_logout` parameter defaults to `false`.
+`true` the client can reuse any persisted state.
-
+
-A client that receives such a response can try to [refresh its access
+{{% changed-in v="1.3" %}} A client that receives such a response can try to
-token](#refreshing-access-tokens), if it has a refresh token
+[refresh its access token](#refreshing-access-tokens), if it has a refresh
-available. If it does not have a refresh token available, or
+token available. If it does not have a refresh token available, or refreshing
-refreshing fails with `soft_logout: true`, the client can acquire a
+fails with `soft_logout: true`, the client can acquire a new access token by
-new access token by specifying the device ID it is already using to
+specifying the device ID it is already using to the login API.
-the login API.
 
 ### User-Interactive Authentication API
 

data/api/client-server/refresh.yaml

@@ -42,6 +42,9 @@ paths:
         not make any assumptions about the old access token still being valid,
         and should use the newly provided access token instead.
 
+        The old refresh token remains valid until the new access token or refresh token
+        is used, at which point the old refresh token is revoked.
+
         Note that this endpoint does not require authentication, since
         authentication is provided via the refresh token.