Merge f95dcfb0e7 into 7066694571

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

changelogs/client_server/newsfragments/2270.feature

@@ -0,0 +1 @@
+Add the account management capabilities for the OAuth 2.0 authentication API, as per [MSC4191](https://github.com/matrix-org/matrix-spec-proposals/pull/4191).

changelogs/client_server/newsfragments/2272.feature

@@ -0,0 +1 @@
+Add OAuth 2.0 aware clients, as per [MSC3824](https://github.com/matrix-org/matrix-spec-proposals/pull/3824).

changelogs/client_server/newsfragments/2278.feature

@@ -0,0 +1 @@
+Add endpoints to lock and suspend server-local users for administrations and add the `m.account_management` capability, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323).

changelogs/client_server/newsfragments/2278.new.1

@@ -0,0 +1 @@
+Add `GET /_matrix/client/v1/admin/suspend/{userId}`, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323).

changelogs/client_server/newsfragments/2278.new.2

@@ -0,0 +1 @@
+Add `PUT /_matrix/client/v1/admin/suspend/{userId}`, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323).

changelogs/client_server/newsfragments/2278.new.3

@@ -0,0 +1 @@
+Add `GET /_matrix/client/v1/admin/lock/{userId}`, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323).

changelogs/client_server/newsfragments/2278.new.4

@@ -0,0 +1 @@
+Add `PUT /_matrix/client/v1/admin/lock/{userId}`, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323).

content/client-server-api/_index.md

@@ -480,6 +480,13 @@ Currently the OAuth 2.0 API doesn't cover all the use cases of the legacy API,
 such as automated applications that cannot use a web browser.
 {{% /boxes/note %}}
 
+{{% boxes/note %}}
+{{% added-in v="1.18" %}}
+A compatibility feature, called [OAuth 2.0 aware clients](#oauth-20-aware-clients),
+is available to ease the transition to the OAuth 2.0 API for clients that only
+support the legacy API.
+{{% /boxes/note %}}
+
 ### Authentication API discovery
 
 To discover if a homeserver supports the legacy API, the [`GET /login`](#get_matrixclientv3login)
@@ -645,7 +652,7 @@ manage their account like [changing their password](#password-management),
 [deactivating their account](#account-deactivation).
 
 With the OAuth 2.0 API, all account management is done via the homeserver's web
-UI.
+UI that can be accessed by users via the [account management URL](#oauth-20-account-management).
 
 ### Legacy API
 
@@ -1612,6 +1619,73 @@ MAY reject weak passwords with an error code `M_WEAK_PASSWORD`.
 
 {{% http-api spec="client-server" api="account_deactivation" %}}
 
+#### OAuth 2.0 aware clients
+
+{{% added-in v="1.18" %}}
+
+This is a compatibility feature to aide clients in the transition to the OAuth
+2.0 API. It allows clients that only support the legacy API to make some
+less-invasive changes to improve the user experience when talking to a
+homeserver that is using the OAuth 2.0 API without actually having to implement
+the full OAuth 2.0 API.
+
+##### Client behaviour
+
+For a client to be considered fully OAuth 2.0 aware it MUST:
+
+* Support the [`m.login.sso` authentication flow](#client-login-via-sso).
+* Where a `oauth_aware_preferred` value of `true` is present on an `m.login.sso`
+  flow, *only* offer that auth flow to the user.
+* Append `action=login` or `action=register` parameters to the [SSO redirect
+  endpoints](#get_matrixclientv3loginssoredirect). The client might determine
+  the value to use based on whether the user clicked a "Login" or "Register"
+  button.
+* Check and honour the [`m.3pid_changes` capability](#m3pid_changes-capability)
+  so that the user is not offered the ability to add or remove 3PIDs if the
+  homeserver says the capability is not available.
+* Determine if the homeserver is using the OAuth 2.0 API by using
+  [server metadata discovery](#get_matrixclientv1auth_metadata) from the OAuth
+  2.0 API.
+* If a homeserver is using the OAuth 2.0 API as discovered in the previous step
+  then the client MUST redirect users to manage their account at the [account
+  management URL](#oauth-20-account-management), if available, instead of
+  providing a native UI using the legacy API endpoints.
+  
+  * If the user wishes to deactivate their account then the client MUST refer
+    them to the account management URL.
+  * If the user wishes to sign out a device other than its own then the client
+    MUST deep link the user to the account management URL by adding the
+    `action=org.matrix.device_delete` and `device_id=<device_id>` parameters so
+    that the web UI knows that the user wishes to sign out a device and which
+    one it is.
+
+Optionally, an OAuth 2.0 aware client MAY:
+
+* Label the SSO button as "Continue" rather than "SSO" when
+  `oauth_aware_preferred` is `true`. This is because after redirect the server
+  may then offer a password and/or further upstream IdPs.
+* Pass other [account management URL parameters](#account-management-url-parameters)
+  for context when linking to the account web UI.
+
+##### Server behaviour
+
+For a homeserver to provide support for OAuth 2.0 aware clients it MUST:
+
+* Support the [OAuth 2.0 API](#oauth-20-api).
+* Provide an implementation of the [`m.login.sso` authentication flow](#client-login-via-sso)
+  from the legacy API.
+* If password authentication was previously enabled on the homeserver then
+  provide an implementation of the [`m.login.password` authentication flow](#legacy-login)
+  from the legacy API.
+* Indicate that the `m.login.sso` flow is preferred by setting
+  `oauth_aware_preferred` to `true`.
+* Support a value for the `action` param on the [SSO redirect endpoints](#get_matrixclientv3loginssoredirect).
+
+Additionally, the homeserver SHOULD:
+
+* Advertise the [account management URL](#oauth-20-account-management) in the
+  [server metadata](#get_matrixclientv1auth_metadata).
+
 ### OAuth 2.0 API
 
 {{% added-in v="1.15" %}}
@@ -2271,6 +2345,46 @@ The server SHOULD return one of the following responses:
 - For other errors, the server returns a `400 Bad Request` response with error
   details
 
+#### Account management {id="oauth-20-account-management"}
+
+{{% added-in v="1.18" %}}
+
+All account management is done via the homeserver's web UI.
+
+This specification defines extensions to the [OAuth Authorization Server
+Metadata registry](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#authorization-server-metadata)
+to offer clients a way to deep-link to the account management capabilities of
+the homeserver to allow the user to complete the account management operations
+in a browser.
+
+##### Account management URL discovery
+
+The [OAuth 2.0 authorization server metadata](#server-metadata-discovery) is
+extended to include the following **optional** fields.
+
+{{% definition path="schemas/oauth2-account-management-server-metadata" %}}
+
+##### Account management URL parameters
+
+The account management URL MAY accept the following minimum query parameters.
+
+{{% definition path="schemas/oauth2-account-management-url" %}}
+
+##### Account management URL actions
+
+Account management actions are unique to the application. They SHOULD follow the
+[Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar)
+where feasible. The Matrix-specific actions are:
+
+| Action                           | Description                                                                                                                                          |
+|----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `org.matrix.profile`             | The user wishes to view/edit their profile (name, avatar, contact details).                                                                          |
+| `org.matrix.devices_list`        | The user wishes to view a list of their devices.                                                                                                     |
+| `org.matrix.device_view`         | The user wishes to view the details of a specific device. A `device_id` SHOULD be provided.                                                          |
+| `org.matrix.device_delete`       | The user wishes to delete/log out a specific device. A `device_id` SHOULD be provided.                                                               |
+| `org.matrix.account_deactivate`  | The user wishes to deactivate their account.                                                                                                         |
+| `org.matrix.cross_signing_reset` | The user wishes to reset their cross-signing identity. Servers SHOULD use this action in the URL of the [`m.oauth`](#oauth-authentication) UIA type. |
+
 ### Account moderation
 
 #### Account locking
@@ -2280,9 +2394,12 @@ The server SHOULD return one of the following responses:
 Server administrators may apply locks to prevent users from usefully
 using their accounts, for instance, due to safety or security concerns.
 In contrast to account deactivation, locking is a non-destructive action
-that can be reversed. This specification describes the behaviour of clients
-and servers when an account is locked. It deliberately leaves the methods
-for locking and unlocking accounts as a server implementation detail.
+that can be reversed.
+
+{{% added-in v="1.18" %}} To lock or unlock an account, the administrators
+SHOULD use the [`PUT /admin/lock/{userId}`](#put_matrixclientv1adminlockuserid)
+endpoint. They MAY also use [`GET /admin/lock/{userId}`](#get_matrixclientv1adminlockuserid)
+to check whether a user's account is locked.
 
 When an account is locked, servers MUST return a `401 Unauthorized` error
 response with an `M_USER_LOCKED` error code and [`soft_logout`](#soft-logout)
@@ -2331,6 +2448,11 @@ from that account. The effect is similar to [locking](#account-locking), though
 without risk of the client losing state from a logout. Suspensions are reversible,
 like locks and unlike deactivations.
 
+{{% added-in v="1.18" %}} To suspend or unsuspend an account, the administrators
+SHOULD use the [`PUT /admin/suspend/{userId}`](#put_matrixclientv1adminsuspenduserid)
+endpoint. They MAY also use [`GET /admin/suspend/{userId}`](#get_matrixclientv1adminsuspenduserid)
+to check whether a user's account is suspended.
+
 The actions a user can perform while suspended is deliberately left as an
 implementation detail. Servers SHOULD permit the user to perform at least the
 following, however:
@@ -2386,9 +2508,6 @@ Content-Type: application/json
 }
 ```
 
-APIs for initiating suspension or unsuspension are not included in this version
-of the specification, and left as an implementation detail.
-
 ### Adding Account Administrative Contact Information
 
 A homeserver may keep some contact information for administrative use.

data/api/client-server/account_deactivation.yaml

@@ -35,6 +35,14 @@ paths:
         Unlike other endpoints, this endpoint does not take an `id_access_token`
         parameter because the homeserver is expected to sign the request to the
         identity server instead.
+
+        {{% boxes/warning %}}
+        {{% added-in v="1.18" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients)
+        MUST NOT use this endpoint when the server supports the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        Instead they MUST refer the user to the [account management URL](/client-server-api/#oauth-20-account-management),
+        if available, and MAY use the `action=org.matrix.account_deactivate`
+        parameter.
+        {{% /boxes/warning %}}
       security:
         - {}
         - accessTokenQuery: []

data/api/client-server/admin.yaml

@@ -16,7 +16,7 @@ info:
   title: Matrix Client-Server Administration API
   version: 1.0.0
 paths:
-  "/admin/whois/{userId}":
+  "/v3/admin/whois/{userId}":
     get:
       summary: Gets information about a particular user.
       description: |-
@@ -107,6 +107,391 @@ paths:
                   }
       tags:
         - Server administration
+  "/v1/admin/suspend/{userId}":
+    get:
+      summary: Gets information about the suspended status of a particular user.
+      x-addedInMatrixVersion: "1.18"
+      description: |-
+        Gets information about the suspended status of a particular server-local user.
+
+        The user calling this endpoint MUST be a server admin.
+
+        In order to prevent user enumeration, servers MUST ensure that authorization is checked
+        prior to trying to do account lookups.
+      operationId: getAdminSuspendUser
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: userId
+          description: The user to look up.
+          required: true
+          example: "@peter:rabbit.rocks"
+          schema:
+            type: string
+            format: mx-user-id
+            pattern: "^@"
+
+      responses:
+        "200":
+          description: The lookup was successful.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  suspended:
+                    type: boolean
+                    description: Whether the target account is suspended.
+                    example: true
+                required:
+                  - suspended
+              examples:
+                response:
+                  value: {
+                    "suspended": true,
+                  }
+        "400":
+          description: |-
+            The user ID does not belong to the local server. The errcode is `M_INVALID_PARAM`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "User does not belong to the local server."
+                  }
+        "403":
+          description: |-
+            The requesting user is not a server administrator, or the target user is another
+            administrator. The errcode is `M_FORBIDDEN`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "Requesting user is not a server administrator."
+                  }
+        "404":
+          description: |-
+            The user ID is not found, or is deactivated. The errcode is `M_NOT_FOUND`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "User not found."
+                  }
+      tags:
+        - Server administration
+    put:
+      summary: Set the suspended status of a particular user.
+      x-addedInMatrixVersion: "1.18"
+      description: |-
+        Sets the suspended status of a particular server-local user.
+
+        The user calling this endpoint MUST be a server admin. The client SHOULD check that the user
+        is allowed to suspend other users at the [`GET /capabilities`](/client-server-api/#get_matrixclientv3capabilities)
+        endpoint prior to using this endpoint.
+
+        In order to prevent user enumeration, servers MUST ensure that authorization is checked
+        prior to trying to do account lookups.
+      operationId: setAdminSuspendUser
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: userId
+          description: The user to change the suspended status of.
+          required: true
+          example: "@peter:rabbit.rocks"
+          schema:
+            type: string
+            format: mx-user-id
+            pattern: "^@"
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                suspended:
+                  type: boolean
+                  description: Whether to suspend the target account.
+                  example: true
+              required:
+                - suspended
+            examples:
+                request:
+                  value: {
+                    "suspended": true,
+                  }
+        required: true
+
+      responses:
+        "200":
+          description: The action was successful.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  suspended:
+                    type: boolean
+                    description: Whether the target account is suspended.
+                    example: true
+                required:
+                  - suspended
+              examples:
+                response:
+                  value: {
+                    "suspended": true,
+                  }
+        "400":
+          description: |-
+            The user ID does not belong to the local server. The errcode is `M_INVALID_PARAM`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "User does not belong to the local server."
+                  }
+        "403":
+          description: |-
+            The requesting user is not a server administrator, is trying to suspend their own
+            account, or the target user is another administrator. The errcode is `M_FORBIDDEN`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "Requesting user is not a server administrator."
+                  }
+        "404":
+          description: |-
+            The user ID is not found, or is deactivated. The errcode is `M_NOT_FOUND`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "User not found."
+                  }
+      tags:
+        - Server administration
+  "/v1/admin/lock/{userId}":
+    get:
+      summary: Gets information about the locked status of a particular user.
+      x-addedInMatrixVersion: "1.18"
+      description: |-
+        Gets information about the locked status of a particular server-local user.
+
+        The user calling this endpoint MUST be a server admin.
+
+        In order to prevent user enumeration, servers MUST ensure that authorization is checked
+        prior to trying to do account lookups.
+      operationId: getAdminLockUser
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: userId
+          description: The user to look up.
+          required: true
+          example: "@peter:rabbit.rocks"
+          schema:
+            type: string
+            format: mx-user-id
+            pattern: "^@"
+
+      responses:
+        "200":
+          description: The lookup was successful.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  locked:
+                    type: boolean
+                    description: Whether the target account is locked.
+                required:
+                  - locked
+              examples:
+                response:
+                  value: {
+                    "locked": true,
+                  }
+        "400":
+          description: |-
+            The user ID does not belong to the local server. The errcode is `M_INVALID_PARAM`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "User does not belong to the local server."
+                  }
+        "403":
+          description: |-
+            The requesting user is not a server administrator, or the target user is another
+            administrator. The errcode is `M_FORBIDDEN`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "Requesting user is not a server administrator."
+                  }
+        "404":
+          description: |-
+            The user ID is not found, or is deactivated. The errcode is `M_NOT_FOUND`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "User not found."
+                  }
+      tags:
+        - Server administration
+    put:
+      summary: Set the locked status of a particular user.
+      x-addedInMatrixVersion: "1.18"
+      description: |-
+        Sets the locked status of a particular server-local user.
+
+        The user calling this endpoint MUST be a server admin. The client SHOULD check that the user
+        is allowed to lock other users at the [`GET /capabilities`](/client-server-api/#get_matrixclientv3capabilities)
+        endpoint prior to using this endpoint.
+
+        In order to prevent user enumeration, servers MUST ensure that authorization is checked
+        prior to trying to do account lookups.
+      operationId: setAdminLockUser
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: userId
+          description: The user to change the locked status of.
+          required: true
+          example: "@peter:rabbit.rocks"
+          schema:
+            type: string
+            format: mx-user-id
+            pattern: "^@"
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                locked:
+                  type: boolean
+                  description: Whether to lock the target account.
+                  example: true
+              required:
+                - locked
+            examples:
+                request:
+                  value: {
+                    "locked": true,
+                  }
+        required: true
+
+      responses:
+        "200":
+          description: The action was successful.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  locked:
+                    type: boolean
+                    description: Whether the target account is locked.
+                    example: true
+                required:
+                  - locked
+              examples:
+                response:
+                  value: {
+                    "locked": true,
+                  }
+        "400":
+          description: |-
+            The user ID does not belong to the local server. The errcode is `M_INVALID_PARAM`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "User does not belong to the local server."
+                  }
+        "403":
+          description: |-
+            The requesting user is not a server administrator, is trying to lock their own
+            account, or the target user is another administrator. The errcode is `M_FORBIDDEN`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "Requesting user is not a server administrator."
+                  }
+        "404":
+          description: |-
+            The user ID is not found, or is deactivated. The errcode is `M_NOT_FOUND`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "User not found."
+                  }
+      tags:
+        - Server administration
 servers:
   - url: "{protocol}://{hostname}{basePath}"
     variables:
@@ -118,7 +503,7 @@ servers:
       hostname:
         default: localhost:8008
       basePath:
-        default: /_matrix/client/v3
+        default: /_matrix/client
 components:
   securitySchemes:
     accessTokenQuery:

data/api/client-server/capabilities.yaml

@@ -78,7 +78,7 @@ paths:
                         description: |
                           **Deprecated:** Capability to indicate if the user can change their display name.
                           Refer to `m.profile_fields` for extended profile management.
-                          
+
                           For backwards compatibility, servers that directly or indirectly include the
                           `displayname` profile field in the `m.profile_fields` capability MUST also
                           set this capability accordingly.
@@ -115,7 +115,7 @@ paths:
                             description: |
                               If present, a list of profile fields that clients are allowed to create, modify or delete,
                               provided `enabled` is `true`; no other profile fields may be changed.
-                              
+
                               If absent, clients may set all profile fields except those forbidden by the `disallowed`
                               list, where present.
                             items:
@@ -127,7 +127,7 @@ paths:
                             type: array
                             description:  |
                               This property has no meaning if `allowed` is also specified.
-                              
+
                               Otherwise, if present, a list of profile fields that clients are _not_ allowed to create, modify or delete.
                               Provided `enabled` is `true`, clients MAY assume that they can set any profile field which is not
                               included in this list.
@@ -141,6 +141,34 @@ paths:
                             example: true
                         required:
                           - enabled
+                      m.account_moderation:
+                        x-addedInMatrixVersion: "1.18"
+                        type: object
+                        title: AccountModerationCapability
+                        description: |-
+                          Capability to indicate if the user can perform account moderation actions
+                          via [server administration](/client-server-api/#server-administration)
+                          endpoints.
+
+                          This property should be omitted altogether if `suspend` and `lock` would
+                          be `false`.
+                        properties:
+                          suspend:
+                            type: boolean
+                            description: |-
+                              `true` if the user can suspend a user via [`PUT /admin/suspend/{userId}`](/client-server-api/#put_matrixclientv1adminsuspenduserid),
+                              `false` otherwise.
+
+                              Defaults to `false`.
+                            example: true
+                          lock:
+                            type: boolean
+                            description: |-
+                              `true` if the user can lock a user via [`PUT /admin/lock/{userId}`](/client-server-api/#put_matrixclientv1adminlockuserid),
+                              `false` otherwise.
+
+                              Defaults to `false`.
+                            example: true
               examples:
                 response:
                   value: {

data/api/client-server/definitions/sso_login_flow.yaml

@@ -86,5 +86,13 @@ properties:
             brand usage as intended by the server.
           example: "github"
       required: ['id', 'name']
+  oauth_aware_preferred:
+    type: boolean
+    x-addedInMatrixVersion: "1.18"
+    description: |
+      Whether the `m.login.sso` flow is preferred over other flows. If this is `true`,
+      [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients) MUST only
+      offer this flow to the user.
+    example: true
 
 required: ['type']

data/api/client-server/device_management.yaml

@@ -170,6 +170,13 @@ paths:
         When this endpoint requires User-Interactive Authentication, it cannot be used when the access token was obtained
         via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
         {{% /boxes/warning %}}
+
+        {{% boxes/warning %}}
+        {{% added-in v="1.18" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients)
+        MUST NOT use this endpoint when the server supports the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        Instead they MUST refer the user to the [account management URL](/client-server-api/#oauth-20-account-management),
+        if available, with the `action=org.matrix.device_delete` and `device_id={deviceId}` parameters.
+        {{% /boxes/warning %}}
       operationId: deleteDevice
       security:
         - accessTokenQuery: []
@@ -232,6 +239,13 @@ paths:
         When this endpoint requires User-Interactive Authentication, it cannot be used when the access token was obtained
         via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
         {{% /boxes/warning %}}
+
+        {{% boxes/warning %}}
+        {{% added-in v="1.18" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients)
+        MUST NOT use this endpoint when the server supports the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        Instead they MUST refer the user to the [account management URL](/client-server-api/#oauth-20-account-management),
+        if available.
+        {{% /boxes/warning %}}
       operationId: deleteDevices
       security:
         - accessTokenQuery: []

data/api/client-server/oauth_server_metadata.yaml

@@ -139,6 +139,32 @@ paths:
                     items:
                       type: string
                       description: A prompt value that the server supports.
+                  account_management_uri:
+                    x-addedInMatrixVersion: "1.18"
+                    type: string
+                    format: uri
+                    description: |-
+                      The URL where the user is able to access the account management capabilities
+                      of the homeserver.
+
+                      This is an extension [defined in this specification](/client-server-api/#oauth-20-account-management).
+                  account_management_actions_supported:
+                    x-addedInMatrixVersion: "1.18"
+                    type: array
+                    description: |-
+                      List of actions that the account management URL supports.
+
+                      This is an extension [defined in this specification](/client-server-api/#oauth-20-account-management).
+                    items:
+                      type: string
+                      enum:
+                        - "org.matrix.profile"
+                        - "org.matrix.devices_list"
+                        - "org.matrix.device_view"
+                        - "org.matrix.device_delete"
+                        - "org.matrix.account_deactivate"
+                        - "org.matrix.cross_signing_reset"
+                      description: An action that the account management URL supports.
                 required:
                   - issuer
                   - authorization_endpoint
@@ -159,6 +185,15 @@ paths:
                   "grant_types_supported": ["authorization_code", "refresh_token"],
                   "response_modes_supported": ["query", "fragment"],
                   "code_challenge_methods_supported": ["S256"],
+                  "account_management_uri": "https://account.example.com/manage",
+                  "account_management_actions_supported": [
+                    "org.matrix.profile",
+                    "org.matrix.devices_list",
+                    "org.matrix.device_view",
+                    "org.matrix.device_delete",
+                    "org.matrix.account_deactivate",
+                    "org.matrix.cross_signing_reset",
+                  ],
                 }
       tags:
         - Session management

data/api/client-server/registration.yaml

@@ -72,6 +72,15 @@ paths:
         `inhibit_login` parameter is not set to `true`, the server MUST return a
         400 HTTP status code with an `M_APPSERVICE_LOGIN_UNSUPPORTED` error code.
         {{% /boxes/note %}}
+
+        {{% boxes/warning %}}
+        {{% added-in v="1.18" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients)
+        MUST NOT use this endpoint when the server offers the [`m.login.sso`
+        authentication flow](/client-server-api/#client-login-via-sso) with
+        `oauth_aware_preferred` set to `true`. Instead they MUST use the
+        [`/login/sso/redirect`](/client-server-api/#get_matrixclientv3loginssoredirect)
+        endpoint, adding the `action=register` parameter.
+        {{% /boxes/warning %}}
       operationId: register
       parameters:
         - in: query

data/api/client-server/sso_login_redirect.yaml

@@ -37,6 +37,22 @@ paths:
           required: true
           schema:
             type: string
+        - in: query
+          name: action
+          x-addedInMatrixVersion: "1.18"
+          description: |-
+            The action that the user wishes to take at the SSO redirect.
+
+            The following values are supported:
+              * `login`: the SSO redirect is for the purposes of signing an
+                existing user in.
+              * `register`: the SSO redirect is for the purpose of registering a
+                new user account.
+          schema:
+            type: string
+            enum:
+              - login
+              - register
       responses:
         "302":
           description: A redirect to the SSO interface.
@@ -75,6 +91,22 @@ paths:
           required: true
           schema:
             type: string
+        - in: query
+          name: action
+          x-addedInMatrixVersion: "1.18"
+          description: |-
+            The action that the user wishes to take at the SSO redirect.
+
+            The following values are supported:
+              * `login`: the SSO redirect is for the purposes of signing an
+                existing user in.
+              * `register`: the SSO redirect is for the purpose of registering a
+                new user account.
+          schema:
+            type: string
+            enum:
+              - login
+              - register
       responses:
         "302":
           description: A redirect to the SSO interface.

data/schemas/oauth2-account-management-server-metadata.yaml

@@ -0,0 +1,30 @@
+# Copyright 2026 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+type: object
+title: OAuth 2.0 Server Metadata Account Management Extension
+properties:
+  account_management_uri:
+    type: string
+    format: uri
+    description: |-
+      The URL where the user is able to access the account management capabilities of the
+      server.
+  account_management_actions_supported:
+    type: array
+    description: |-
+      List of [actions](/client-server-api/#account-management-url-actions) that the account
+      management URL supports.
+    items:
+      type: string
+      description: An action that the account management URL supports.

data/schemas/oauth2-account-management-url.yaml

@@ -0,0 +1,29 @@
+# Copyright 2026 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+type: object
+title: OAuth 2.0 Account Management URL Query Parameters
+properties:
+  action:
+    type: string
+    description: |-
+      The action that the user wishes to take. Must match one of the actions advertised by the
+      server in [`account_management_actions_supported`](/client-server-api/#account-management-url-discovery).
+  device_id:
+    type: string
+    description: |-
+      For Matrix-specific actions, the user's device ID. Actions which don't support the device ID
+      will ignore it.
+
+      If the `org.matrix.device_view` or `org.matrix.device_delete` actions are advertised as
+      supported by the server then the server SHOULD support the `device_id` parameter.