Remove duplicate endpoint behavior

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

content/application-service-api.md

@@ -446,11 +446,12 @@ achieved by including the `as_token` on a `/register` request, along
 with a login type of `m.login.application_service` to set the desired
 user ID without a password.
 
-```
+```http
 POST /_matrix/client/v3/register
 Authorization: Bearer YourApplicationServiceTokenHere
+```
 
-Content:
+```json
 {
   "type": "m.login.application_service",
   "username": "_irc_example"
@@ -476,11 +477,12 @@ along with a login type of `m.login.application_service`:
 
 {{% added-in v="1.2" %}}
 
-```
+```http
 POST /_matrix/client/v3/login
 Authorization: Bearer YourApplicationServiceTokenHere
+```
 
-Content:
+```json
 {
   "type": "m.login.application_service",
   "identifier": {
@@ -545,19 +547,13 @@ client-server endpoint.
 Application services need to be able to create and delete devices to manage the
 encryption for their users without having to rely on `/login`, which also
 generates an access token for the user, and which might not be available for
-homeservers that only support the [OAuth 2.0 API](client-server-api/#oauth-20-api).
+homeservers that only support the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
 
 ##### Creating devices
 
 Application services can use the [`PUT /_matrix/client/v3/devices/{deviceId}`](/client-server-api/#put_matrixclientv3devicesdeviceid)
 endpoint to create new devices.
 
-When a new device was created, the homeserver MUST return a 201 HTTP status code.
-It MUST still return a 200 HTTP status code if a device was updated.
-
-This endpoint is rate-limited for device creation. Servers MAY want to use login
-rate limits.
-
 ##### Deleting devices
 
 The following endpoints used to delete devices MUST NOT require [User-Interactive

data/api/client-server/cross_signing.yaml

@@ -21,13 +21,17 @@ paths:
       x-addedInMatrixVersion: "1.1"
       x-changedInMatrixVersion:
         "1.11": UIA is not always required for this endpoint.
+        "1.17": |-
+          This endpoint no longer requires User-Interactive Authentication when used by an
+          application service.
       summary: Upload cross-signing keys.
       description: |-
         Publishes cross-signing keys for the user.
 
-        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
+        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api),
+        except when used by an application service.
 
-        User-Interactive Authentication MUST be performed, except in these cases:
+        User-Interactive Authentication MUST be performed for regular clients, except in these cases:
         - there is no existing cross-signing master key uploaded to the homeserver, OR
         - there is an existing cross-signing master key and it exactly matches the
           cross-signing master key provided in the request body. If there are any additional
@@ -46,12 +50,6 @@ paths:
         authentication type if the access token was obtained
         via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
         {{% /boxes/note %}}
-
-        {{% boxes/note %}}
-        {{% added-in v="1.17" %}}
-        When this endpoint is used by an application service, the server MUST NOT require
-        User-Interactive Authentication, even if cross-signing keys already exist.
-        {{% /boxes/note %}}
       operationId: uploadCrossSigningKeys
       security:
         - accessTokenQuery: []

data/api/client-server/device_management.yaml

@@ -88,20 +88,20 @@ paths:
         - Device management
     put:
       summary: Create or update a device
+      x-changedInMatrixVersion:
+        "1.17": The ability to create new devices was added.
       description: |-
-        Updates the metadata on the given device.
+        Updates the metadata on the given device, or creates a new device.
 
-        {{% boxes/note %}}
+        The ability to create new devices is only available to application
-        {{% added-in v="1.17" %}}
+        services: regular clients may only update existing devices.
-        This endpoint can be used by application services to create a device.
 
         When a new device was created, the homeserver MUST return a 201 HTTP
-        status code. It MUST still return a 200 HTTP status code if a device was
+        status code. It MUST return a 200 HTTP status code if a device was
         updated.
 
-        This endpoint is rate-limited for device creation. Servers MAY want to
+        This endpoint is rate-limited for device creation. Servers MAY use login
-        use login rate limits.
+        rate limits.
-        {{% /boxes/note %}}
       operationId: updateDevice
       security:
         - accessTokenQuery: []
@@ -156,21 +156,20 @@ paths:
         - Device management
     delete:
       summary: Delete a device
+      x-changedInMatrixVersion:
+        "1.17": |-
+          This endpoint no longer requires User-Interactive Authentication when used by an
+          application service.
       description: |-
-        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
+        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api),
+        except when used by an application service.
 
         Deletes the given device, and invalidates any access token associated with it.
 
         {{% boxes/warning %}}
-        Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained
+        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/note %}}
-        {{% added-in v="1.17" %}}
-        When this endpoint is used by an application service, the server MUST NOT
-        require User-Interactive Authentication.
-        {{% /boxes/note %}}
       operationId: deleteDevice
       security:
         - accessTokenQuery: []
@@ -219,21 +218,20 @@ paths:
   /delete_devices:
     post:
       summary: Bulk deletion of devices
+      x-changedInMatrixVersion:
+        "1.17": |-
+          This endpoint no longer requires User-Interactive Authentication when used by an
+          application service.
       description: |-
-        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
+        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api),
+        except when used by an application service.
 
         Deletes the given devices, and invalidates any access token associated with them.
 
         {{% boxes/warning %}}
-        Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained
+        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/note %}}
-        {{% added-in v="1.17" %}}
-        When this endpoint is used by an application service, the server MUST NOT
-        require User-Interactive Authentication.
-        {{% /boxes/note %}}
       operationId: deleteDevices
       security:
         - accessTokenQuery: []

data/api/client-server/login.yaml

@@ -243,8 +243,13 @@ paths:
                     }
                   }
         "400":
-          description: Part of the request was invalid. For example, the login type may
+          description: |-
-            not be recognised.
+            Part of the request was invalid. For example, the login type may not be recognised.
+
+            Specific error codes used with this status code include:
+              * {{% added-in v="1.17" %}} `M_APPSERVICE_LOGIN_UNSUPPORTED`: an application service
+                used the `m.login.application_service` type, but the server doesn't support logging
+                in via the Legacy authentication API.
           content:
             application/json:
               schema:

data/api/client-server/registration.yaml

@@ -215,6 +215,9 @@ paths:
             * `M_INVALID_USERNAME` : The desired user ID is not a valid user name.
             * `M_EXCLUSIVE` : The desired user ID is in the exclusive namespace
               claimed by an application service.
+            * {{% added-in v="1.17" %}} `M_APPSERVICE_LOGIN_UNSUPPORTED`: an application service
+              used the `m.login.application_service` type without setting `inhibit_login` to `true`,
+              but the server doesn't support logging in via the Legacy authentication API.
 
             These errors may be returned at any stage of the registration process,
             including after authentication if the requested user ID was registered