Merge cf45f4d17b into 2c734c3c5b

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

changelogs/client_server/newsfragments/2141.clarification

@@ -0,0 +1 @@
+Split account registration and management section and OpenAPI definitions.

changelogs/client_server/newsfragments/2141.feature

@@ -1 +0,0 @@
-Add the OAuth 2.0 based authentication API, as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and its sub-proposals.

content/client-server-api/_index.md

@@ -560,11 +560,9 @@ specifying the device ID it is already using to the login API.
 with an `M_USER_LOCKED` error code, cannot obtain a new access token until
 the account has been [unlocked](#account-locking).
 
-### Legacy API
+### User-Interactive Authentication API
 
-#### User-Interactive Authentication API
-
-##### Overview
+#### Overview
 
 Some API endpoints require authentication that interacts with the user.
 The homeserver may provide many different ways of authenticating, such
@@ -588,7 +586,7 @@ the flows in order must result in an HTTP 401 response, as defined
 below. When all stages in a flow are complete, authentication is
 complete and the API call succeeds.
 
-##### User-interactive API in the REST API
+#### User-interactive API in the REST API
 
 In the REST API described in this specification, authentication works by
 the client and server exchanging JSON dictionaries. The server indicates
@@ -766,7 +764,7 @@ auth by offering a stage with only the `m.login.dummy` auth type, but they
 must still give a 401 response to requests with no auth data.
 {{% /boxes/note %}}
 
-**Example**
+#### Example
 
 At a high level, the requests made for an API call completing an auth
 flow with three stages will resemble the following diagram:
@@ -808,7 +806,7 @@ flow with three stages will resemble the following diagram:
     |_______________________|
 ```
 
-##### Authentication types
+#### Authentication types
 
 This specification defines the following auth types:
 -   `m.login.password`
@@ -819,7 +817,7 @@ This specification defines the following auth types:
 -   `m.login.dummy`
 -   `m.login.registration_token`
 
-###### Password-based
+##### Password-based
 
 
 | Type               | Description                                                                    |
@@ -878,7 +876,7 @@ explicitly as follows:
 In the case that the homeserver does not know about the supplied 3PID,
 the homeserver must respond with 403 Forbidden.
 
-###### Google ReCaptcha
+##### Google ReCaptcha
 
 | Type                | Description                                          |
 |---------------------|------------------------------------------------------|
@@ -895,7 +893,7 @@ follows:
 }
 ```
 
-###### Single Sign-On
+##### Single Sign-On
 
 | Type          | Description                                                                          |
 |---------------|--------------------------------------------------------------------------------------|
@@ -905,7 +903,7 @@ A client wanting to complete authentication using SSO should use the
 [Fallback](#fallback) mechanism. See [SSO during User-Interactive
 Authentication](#sso-during-user-interactive-authentication) for more information.
 
-###### Email-based (identity / homeserver)
+##### Email-based (identity / homeserver)
 
 | Type                     | Description                                                                                                      |
 |--------------------------|------------------------------------------------------------------------------------------------------------------|
@@ -934,7 +932,7 @@ follows:
 Note that `id_server` (and therefore `id_access_token`) is optional if
 the [`/requestToken`](#post_matrixclientv3registeremailrequesttoken) request did not include them.
 
-###### Phone number/MSISDN-based (identity / homeserver)
+##### Phone number/MSISDN-based (identity / homeserver)
 
 | Type             | Description                                                                                                    |
 |------------------|----------------------------------------------------------------------------------------------------------------|
@@ -963,7 +961,7 @@ follows:
 Note that `id_server` (and therefore `id_access_token`) is optional if
 the [`/requestToken`](#post_matrixclientv3registermsisdnrequesttoken) request did not include them.
 
-###### Dummy Auth
+##### Dummy Auth
 
 | Type             | Description                                                            |
 |------------------|------------------------------------------------------------------------|
@@ -989,7 +987,7 @@ just the type and session, if provided:
 }
 ```
 
-###### Token-authenticated registration
+##### Token-authenticated registration
 
 {{% added-in v="1.2" %}}
 
@@ -1033,7 +1031,7 @@ in the registration process that their token has expired.
 
 {{% http-api spec="client-server" api="registration_tokens" %}}
 
-###### Terms of service at registration
+##### Terms of service at registration
 
 {{% added-in v="1.11" %}}
 
@@ -1156,7 +1154,7 @@ user during registration, if applicable.
 
 {{% definition path="api/client-server/definitions/m.login.terms_params" %}}
 
-##### Fallback
+#### Fallback
 
 Clients cannot be expected to be able to know how to process every
 single login type. If a client does not know how to handle a given login
@@ -1197,7 +1195,7 @@ with just the session ID:
 }
 ```
 
-**Example**
+##### Example
 
 A client webapp might use the following JavaScript to open a popup
 window which will handle unknown login types:
@@ -1253,7 +1251,7 @@ function unknownLoginType(homeserverUrl, apiEndpoint, loginType, sessionID, onCo
 }
 ```
 
-##### Identifier types
+#### Identifier types
 
 Some authentication mechanisms use a user identifier object to identify
 a user. The user identifier object has a `type` field to indicate the
@@ -1266,7 +1264,7 @@ This specification defines the following identifier types:
 -   `m.id.thirdparty`
 -   `m.id.phone`
 
-###### Matrix User ID
+##### Matrix User ID
 
 | Type        | Description                                |
 |-------------|--------------------------------------------|
@@ -1283,7 +1281,7 @@ ID.
 }
 ```
 
-###### Third-party ID
+##### Third-party ID
 
 | Type              | Description                                                               |
 |-------------------|---------------------------------------------------------------------------|
@@ -1303,7 +1301,7 @@ ID media.
 }
 ```
 
-###### Phone number
+##### Phone number
 
 | Type         | Description                               |
 |--------------|-------------------------------------------|
@@ -1329,7 +1327,7 @@ The `country` is the two-letter uppercase ISO-3166-1 alpha-2 country
 code that the number in `phone` should be parsed as if it were dialled
 from.
 
-#### Login
+### Login
 
 A client can obtain access tokens using the [`/login`](#post_matrixclientv3login) API.
 
@@ -1401,7 +1399,7 @@ a token for their user ID if supported by the homeserver using
 
 {{% http-api spec="client-server" api="logout" %}}
 
-##### Appservice Login
+#### Appservice Login
 
 {{% added-in v="1.2" %}}
 
@@ -1438,7 +1436,7 @@ If the access token does correspond to an appservice, but the user id does
 not lie within its namespace then the homeserver will respond with an
 errcode of `M_EXCLUSIVE`.
 
-##### Login Fallback
+#### Login Fallback
 
 If a client does not recognize any or all login flows it can use the
 fallback login API:
@@ -1458,13 +1456,13 @@ forwarded to the login endpoint during the login process. For example:
 
     GET /_matrix/static/client/login/?device_id=GHTYAJCE
 
-#### Account registration
+### Account registration and management
+
+#### Account Registration
 
 {{% http-api spec="client-server" api="registration" %}}
 
-#### Account management
-
-##### Password management
+#### Password management
 
 {{% boxes/warning %}}
 Clients SHOULD enforce that the password provided is suitably complex.
@@ -1475,12 +1473,10 @@ MAY reject weak passwords with an error code `M_WEAK_PASSWORD`.
 
 {{% http-api spec="client-server" api="password_management" %}}
 
-##### Account deactivation
+#### Account deactivation
 
 {{% http-api spec="client-server" api="account_deactivation" %}}
 
-### OAuth 2.0 API
-
 ### Account moderation
 
 #### Account locking