add delete_devices endpoint

fix #1041

api/client-server/device_management.yaml

@@ -177,3 +177,50 @@ paths:
             "$ref": "definitions/auth_response.yaml"
       tags:
         - Device management
+  "/delete_devices":
+    post:
+      summary: Bulk deletion of devices
+      description: |-
+        This API endpoint uses the `User-Interactive Authentication API`_.
+
+        Deletes the given devices, and invalidates any access token associated with them.
+      operationId: deleteDevices
+      security:
+        - accessToken: []
+      parameters:
+        - in: body
+          name: body
+          schema:
+            type: object
+            properties:
+              devices:
+                type: array
+                description: The list of device IDs to delete.
+                items:
+                  type: string
+                  description: A list of device IDs.
+                example: ["QBUAZIFURK", "AUIECTSRND"]
+              auth:
+                description: |-
+                    Additional authentication information for the
+                    user-interactive authentication API.
+                "$ref": "definitions/auth_data.yaml"
+            required:
+              - devices
+      responses:
+        200:
+          description: |-
+            The devices were successfully removed, or had been removed
+            previously.
+          schema:
+            type: object
+          examples:
+            application/json: {
+              }
+        401:
+          description: |-
+            The homeserver requires additional authentication information.
+          schema:
+            "$ref": "definitions/auth_response.yaml"
+      tags:
+        - Device management

changelogs/client_server.rst

@@ -9,6 +9,8 @@ Unreleased changes
       (`#1096 <https://github.com/matrix-org/matrix-doc/pull/1096>`_).
     - ``GET /rooms/{roomId}/event/{eventId}``
       (`#1110 <https://github.com/matrix-org/matrix-doc/pull/1110>`_).
+    - ``POST /delete_devices``
+      (`#1239 <https://github.com/matrix-org/matrix-doc/pull/1239>`_).
 
   - Sticker messages:
     - Add sticker message event definition.