content/client-server-api/_index.md

@@ -1483,11 +1483,12 @@ MAY reject weak passwords with an error code `M_WEAK_PASSWORD`.
 
 #### Grant types
 
-[RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749) and other RFCs define
+OAuth 2.0 defines several ways in [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749)
-several "grant types": ways to obtain an ["access token"](#using-access-tokens).
+and other RFCs to obtain an access token at the token endpoint, these are called
+grants.
 
-All these grants types require the client to know the following authorization
+All these grants require the client to know the following authorization server
-server metadata:
+metadata:
 - `token_endpoint`
 - `grant_types_supported`
 
@@ -1497,6 +1498,11 @@ This specification supports the following grant types:
 - [Authorization code grant](#authorization-code-grant)
 - [Refresh token grant](#refresh-token-grant)
 
+{{% boxes/note %}}
+Other MSCs might add support for more grant types in the future, like [MSC4108](https://github.com/matrix-org/matrix-spec-proposals/pull/4108)
+which makes use of the device code grant.
+{{% /boxes/note %}}
+
 ##### Authorization code grant
 
 As per [RFC 6749 section 4.1](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1),
@@ -1510,102 +1516,53 @@ metadata:
 - `response_mode_supported`
 
 To use this grant, homeservers and clients MUST:
-
+- support the authorization code grant as per [RFC 6749 section 4.1](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1)
-- Support the authorization code grant as per [RFC 6749 section 4.1](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1).
+- support the [refresh token grant](#refresh-token-grant)
-- Support the [refresh token grant](#refresh-token-grant).
+- support PKCE using the `S256` code challenge method as per [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636)
-- Support PKCE using the `S256` code challenge method as per [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636).
+- use pre-registered, strict redirect URIs
-- Use pre-registered, strict redirect URIs.
+- use the `fragment` response mode as per [OAuth 2.0 Multiple Response Type
-- Use the `fragment` response mode as per [OAuth 2.0 Multiple Response Type
   Encoding Practices](https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html)
-  for clients with an HTTPS redirect URI.
+  for clients with an HTTPS redirect URI
 
-###### User registration
+###### Login flow with the authorization code grant
 
-Clients can signal to the server that the user desires to register a new account
+Logging in with the OAuth 2.0 authorization code grant in the context of the
-by initiating the authorization code grant with the `prompt=create` parameter
+Matrix specification means to request a scope including full client-server API
-set in the authorization request as defined in [Initiating User Registration via
-OpenID Connect 1.0](https://openid.net/specs/openid-connect-prompt-create-1_0.html).
-
-Whether the homeserver supports this parameter is advertised by the
-`prompt_values_supported` authorization server metadata.
-
-Servers that support this parameter SHOULD show the account registration UI in
-the browser.
-
-##### Refresh token grant
-
-As per [RFC 6749 section 6](https://datatracker.ietf.org/doc/html/rfc6749#section-6),
-the refresh token grant lets the client exchange a refresh token for an access
-token.
-
-When authorization is granted to a client, the homeserver MUST issue a refresh
-token to the client in addition to the access token.
-
-The access token MUST be short-lived and SHOULD be refreshed using the
-`refresh_token` when expired.
-
-The homeserver SHOULD issue a new refresh token each time an old one is used,
-and invalidate the old one. However, it MUST ensure that the client is able to
-retry the refresh request in the case that the response to the request is lost.
-
-The homeserver SHOULD consider that the session is compromised if an old,
-invalidated refresh token is used, and SHOULD revoke the session.
-
-The client MUST handle access token refresh failures as follows:
-
- - If the refresh fails due to network issues or a `5xx` HTTP status code from
-   the server, the client should retry the request with the old refresh token
-   later.
- - If the refresh fails due to a `4xx` HTTP status code from the server, the
-   client should consider the session logged out.
-
-#### Login flow
-
-Logging in with the OAuth 2.0 API should be done with the [authorization code
-grant](#authorization-code-grant). In the context of the Matrix specification,
-this means requesting a [scope](#scope) including full client-server API
 read/write access and allocating a device ID.
 
 First, the client needs to generate the following values:
 
-- `device_id`: a unique identifier for this device; see the
+- a random value for the `device_id`
-  [`urn:matrix:client:device:<device_id>`] scope.
+- a random value for the `state`
-- `state`: a unique opaque identifier, like a [transaction ID](#transaction-identifiers),
+- a cryptographically random value for the `code_verifier`
-  that will allow the client to maintain state between the authorization request
-  and the callback.
-- `code_verifier`: a cryptographically random value that will allow to make sure
-  that the client that makes the token request for a given `code` is the same
-  one that made the authorization request.
-
-  It is defined in [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636) as
-  a high-entropy cryptographic random string using the characters `[A-Z]`,
-  `[a-z]`, `[0-9]`, `-`, `.`, `_` and `~` with a minimum length of 43 characters
-  and a maximum length of 128 characters.
 
 **Authorization request**
 
-The client then constructs the authorization request URL using the
+It then constructs the authorization request URL using the
 `authorization_endpoint` value, with the following query parameters:
 
-| Parameter               | Value                                              |
+- The `response_type` value set to `code`
-|-------------------------|----------------------------------------------------|
+- The `client_id` value obtained by registering the client metadata with the
-| `response_type`         | `code`                                             |
+  server
-| `client_id`             | The client ID returned from client registration.   |
+- The `redirect_uri` value that MUST match one of the values registered in the
-| `redirect_uri`          | The redirect URI that MUST match one of the values registered in the client metadata |
+  client metadata
-| `scope`                 | `urn:matrix:client:api:* urn:matrix:client:device:<device_id>` with the `device_id` generated previously. |
+- The `scope` value set to `urn:matrix:client:api:* urn:matrix:client:device:<device_id>` with the `device_id` generated previously
-| `state`                 | The `state` value generated previously.            |
+- The `state` value
-| `response_mode`         | `fragment` or `query` (see "[Callback](#callback)" below). |
+- The `response_mode` value
-| `code_challenge`        | Computed from the `code_verifier` value generated previously using the SHA-256 algorithm, as described in [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636) |
+- The `code_challenge` computed from the `code_verifier` value using the SHA-256
-| `code_challenge_method` | `S256`                                             |
+  algorithm, as described in [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636)
+- The `code_challenge_method` set to `S256`
 
 This authorization request URL must be opened in the user's browser:
 
 - For web-based clients, this can be done through a redirection or by opening
-  the URL in a new tab.
+  the URL in a new tab
-- For native clients, this can be done by opening the URL using the system
+- For native clients, this can be done by opening the URL:
-  browser, or, when available, through platform-specific APIs such as
+  - using the system browser
+  - through platform-specific APIs when available, such as
     [`ASWebAuthenticationSession`](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession)
-  on iOS or [Android Custom Tabs](https://developer.chrome.com/docs/android/custom-tabs).
+    on iOS or [Android Custom Tabs](https://developer.chrome.com/docs/android/custom-tabs)
+    on Android
 
 Sample authorization request, with extra whitespaces for readability:
 
@@ -1621,23 +1578,23 @@ https://account.example.com/oauth2/auth?
     code_challenge_method = S256
 ```
 
-<a id="callback"></a> **Callback**
+**Callback**
 
 Once completed, the user is redirected to the `redirect_uri`, with either a
 successful or failed authorization in the URL fragment or query parameters.
 Whether the parameters are in the URL fragment or query parameters is determined
 by the `response_mode` value:
 
-- If set to `fragment`, the parameters will be placed in the URL fragment, like
+- if set to `fragment`, the parameters will be placed in the URL fragment, like
-  `https://example.com/callback#param1=value1&param2=value2`.
+  `https://example.com/callback#param1=value1&param2=value2`
-- If set to `query`, the parameters will be in placed the query string, like
+- if set to `query`, the parameters will be in placed the query string, like
-  `com.example.app:/callback?param1=value1&param2=value2`.
+  `com.example.app:/callback?param1=value1&param2=value2`
 
 To avoid disclosing the parameters to the web server hosting the `redirect_uri`,
-clients SHOULD use the `fragment` response mode if the `redirect_uri` is an
+clients should use the `fragment` response mode if the `redirect_uri` is an
 HTTPS URI with a remote host.
 
-In both success and failure cases, the parameters will include the `state` value
+In both success and failure cases, the parameters will have the `state` value
 used in the authorization request.
 
 A successful authorization will have a `code` value, for example:
@@ -1666,13 +1623,11 @@ the token endpoint.
 This is done by making a POST request to the `token_endpoint` with the following
 parameters, encoded as `application/x-www-form-urlencoded` in the body:
 
-| Parameter       | Value                                                      |
+- The `grant_type` set to `authorization_code`
-|-----------------|------------------------------------------------------------|
+- The `code` obtained from the callback
-| `grant_type`    | `authorization_code`                                       |
+- The `redirect_uri` used in the authorization request
-| `code`          | The value of `code` obtained from the callback.            |
+- The `client_id` value
-| `redirect_uri`  | The same `redirect_uri` used in the authorization request. |
+- The `code_verifier` value generated at the start of the authorization flow
-| `client_id`     | The client ID returned from client registration.           |
-| `code_verifier` | The value generated at the start of the authorization flow. |
 
 The server replies with a JSON object containing the access token, the token
 type, the expiration time, and the refresh token.
@@ -1707,20 +1662,58 @@ Sample response:
 Finally, the client can call the  [`/whoami`](#get_matrixclientv3accountwhoami)
 endpoint to get the user ID that owns the access token.
 
-#### Token refresh flow
+###### User registration
 
-Refreshing a token with the OAuth 2.0 API should be done with the [refresh token
+Clients can signal to the server that the user desires to register a new account
-grant](#refresh-token-grant).
+by initiating the authorization code grant with the `prompt=create` parameter
+set in the authorization request as defined in [Initiating User Registration via
+OpenID Connect 1.0](https://openid.net/specs/openid-connect-prompt-create-1_0.html).
+
+Whether the homeserver supports this parameter is advertised by the
+`prompt_values_supported` authorization server metadata.
+
+Servers that support this parameter SHOULD show the account registration UI in
+the browser.
+
+##### Refresh token grant
+
+As per [RFC 6749 section 6](https://datatracker.ietf.org/doc/html/rfc6749#section-6),
+the refresh token grant lets the client exchange a refresh token for an access
+token.
+
+When authorization is granted to a client, the homeserver MUST issue a refresh
+token to the client in addition to the access token.
+
+The access token MUST be short-lived and SHOULD be refreshed using the
+`refresh_token` when expired.
+
+The homeserver SHOULD issue a new refresh token each time one is used, and
+invalidate the old one. It should do this only if it can guarantee that in case
+a response with a new refresh token is not received and stored by the client,
+retrying the request with the old refresh token will succeed.
+
+The homeserver SHOULD consider that the session is compromised if an old,
+invalidated refresh token is being used, and SHOULD revoke the session.
+
+The client MUST handle access token refresh failures as follows:
+
+ - If the refresh fails due to network issues or a `5xx` HTTP status code from
+   the server, the client should retry the request with the old refresh token
+   later.
+ - If the refresh fails due to a `4xx` HTTP status code from the server, the
+   client should consider the session logged out.
+
+###### Token refresh flow with the refresh token grant
 
 When the access token expires, the client must refresh it by making a `POST`
 request to the `token_endpoint` with the following parameters, encoded as
 `application/x-www-form-urlencoded` in the body:
 
-| Parameter       | Value                                                      |
+- The `grant_type` set to `refresh_token`
-|-----------------|------------------------------------------------------------|
+- The `refresh_token` obtained from the token response during the authorization
-| `grant_type`    | `refresh_token`                                            |
+  flow
-| `refresh_token` | The `refresh_token` obtained from the token response during the last token request. |
+- The `client_id` value obtained by registering the client metadata with the
-| `client_id`     | The client ID returned from client registration.           |
+  server
 
 The server replies with a JSON object containing the new access token, the token
 type, the expiration time, and a new refresh token, like in the authorization