Address review feedback

Co-authored-by: Kévin Commaille <76261501+zecakeh@users.noreply.github.com>

content/client-server-api/_index.md

@@ -523,7 +523,7 @@ endpoint.
 
 With the OAuth 2.0 API, a client can obtain an access token by using one of the
 [grant types](#grant-types) supported by the homeserver and authorizing the
-proper [scope](#scope), as demonstrated in the [login flow](#login-flow). To
+proper [scope](#scope), as demonstrated in the [login flows](#login-flows). To
 invalidate the access token the client must use [token revocation](#token-revocation).
 
 ### Using access tokens
@@ -1720,30 +1720,31 @@ authentication type.
 
 1. [Discover the OAuth 2.0 server metadata](#server-metadata-discovery).
 2. [Register the client with the homeserver](#client-registration).
-3. Obtain an access token by authorizing a [scope](#scope) for the client with
-   one of the supported grant types:
-   - Use the [authorization code grant](#authorization-code-grant) via the
-     [login flow](#login-flow) for clients with access to a web browser.
-   - {{% added-in v="1.18" %}} Use the [device authorization grant](#device-authorization-grant) via the
-     [device authorization flow](#device-authorization-flow) for clients on
-     devices with limited input capabilities (e.g. CLI applications or embedded devices)
-     where the user completes authorization on a separate device.
+3. [Obtain an access token](#login-flows) by authorizing a [scope](#scope) for
+   the client with the [authorization code grant](#authorization-code-grant) or
+   [device authorization grant](#device-authorization-grant).
 4. [Refresh the access token](#token-refresh-flow) with the [refresh token grant](#refresh-token-grant) when it expires.
 5. [Revoke the tokens](#token-revocation) when the users wants to log out of the client.
 
-#### Login flow
+#### Login flows
 
-Logging in with the OAuth 2.0 API should be done with the [authorization code
-grant](#authorization-code-grant) for clients that have access to a web browser.
-For clients on devices with limited input capabilities, the
-[device authorization flow](#device-authorization-flow) can be used instead.
+Logging in and obtaining an access token with the OAuth 2.0 API should be done
+using either the [authorization code grant](#authorization-code-grant) or
+[device authorization grant](#device-authorization-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.
 
-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.
+##### Authorization code flow
 
-Once the client has retrieved the [server metadata](#server-metadata-discovery),
-it needs to generate the following values:
+This login flow uses the [authorization code grant](#authorization-code-grant)
+and is suitable for clients where the following criteria are met:
+
+- There is a web browser available for the user to complete authentication and
+  authorization.
+- The client can receive the callback via a redirect from the web browser.
+
+Once the client has retrieved the [server metadata](#server-metadata-discovery)
+the client needs to generate the following values:
 
 - `device_id`: a unique identifier for this device; see the
   [`urn:matrix:client:device:<device_id>`](#device-id-allocation) scope token.
@@ -1884,25 +1885,21 @@ Sample response:
 Finally, the client can call the  [`/whoami`](#get_matrixclientv3accountwhoami)
 endpoint to get the user ID that owns the access token.
 
-#### Device authorization flow
+##### Device authorization flow
 
 {{% added-in v="1.18" %}}
 
-The device authorization flow allows clients to obtain an access token without
-needing to directly interact with a web browser. Instead, the user completes
-authorization on a web browser that can be on a separate device. This is useful
-for devices with limited input capabilities (such as CLI applications or
-embedded devices) or where the redirect handling may be unreliable (such as a
-desktop applications).
+This flow uses the [device authorization grant](#device-authorization-grant) to
+allow clients to obtain an access token without needing to directly interact
+with a web browser. Instead, the user completes authorization on a web browser
+that can be a separate device.
 
-This flow uses the [device authorization grant](#device-authorization-grant).
+This is useful for devices with limited input
+capabilities (such as CLI applications or embedded devices) or where the
+redirect handling may be unreliable (such as a desktop applications).
 
-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, as with the [login flow](#login-flow).
-
-Once the client has retrieved the [server metadata](#server-metadata-discovery),
-it needs to generate the following value:
+Once the client has retrieved the [server metadata](#server-metadata-discovery)
+the client needs to generate following value:
 
 - `device_id`: a unique identifier for this device; see the
   [`urn:matrix:client:device:<device_id>`](#device-id-allocation) scope token.
@@ -1920,7 +1917,7 @@ the `device_authorization_endpoint` as defined in
 
 Sample device authorization request:
 
-```http
+```
 POST /oauth2/device HTTP/1.1
 Host: account.example.com
 Content-Type: application/x-www-form-urlencoded
@@ -1994,7 +1991,7 @@ parameters, encoded as `application/x-www-form-urlencoded` in the body:
 
 Sample token polling request:
 
-```http
+```
 POST /oauth2/token HTTP/1.1
 Host: account.example.com
 Content-Type: application/x-www-form-urlencoded
@@ -2023,8 +2020,7 @@ The server responds as defined in [RFC 8628 section
 ```
 
 Finally, the client can call the [`/whoami`](#get_matrixclientv3accountwhoami)
-endpoint to get the user ID that owns the access token. Token refreshing and
-revocation proceed as with the [login flow](#login-flow).
+endpoint to get the user ID that owns the access token.
 
 #### Token refresh flow
 
@@ -2381,19 +2377,6 @@ To use this grant, homeservers and clients MUST:
   Encoding Practices](https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html)
   for clients with an HTTPS redirect URI.
 
-###### User registration
-
-Clients can signal to the server that the user desires to register a new account
-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.
-
 ##### Device authorization grant
 
 {{% added-in v="1.18" %}}
@@ -2528,6 +2511,22 @@ The server SHOULD return one of the following responses:
 - For other errors, the server returns a `400 Bad Request` response with error
   details
 
+#### User registration
+
+Clients can signal to the server that the user desires to register a new account
+by initiating the [authorization code grant](#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.
+
+The `prompt=create` parameter is not supported when using the [device
+authorization grant](#device-authorization-grant).
+
 #### Account management {id="oauth-20-account-management"}
 
 {{% added-in v="1.18" %}}

data/api/client-server/oauth_server_metadata.yaml

@@ -67,8 +67,7 @@ paths:
                     type: string
                     format: uri
                     description: |-
-                      URL of the token endpoint, necessary to use the authorization code grant,
-                      device authorization grant and the refresh token grant.
+                      URL of the token endpoint, used by the grants.
                   revocation_endpoint:
                     type: string
                     format: uri