From 55b512c9683a439b9d6d3175cd8c92e8356ee077 Mon Sep 17 00:00:00 2001
From: Valentin Deniaud <valentin.deniaud@inpt.fr>
Date: Mon, 14 May 2018 16:03:38 +0200
Subject: [PATCH] add delete_devices endpoint

fix #1041
---
 api/client-server/device_management.yaml | 47 ++++++++++++++++++++++++
 changelogs/client_server.rst             |  2 +
 2 files changed, 49 insertions(+)

diff --git a/api/client-server/device_management.yaml b/api/client-server/device_management.yaml
index 030ed8311..75ee9e444 100644
--- a/api/client-server/device_management.yaml
+++ b/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
diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst
index c29f38c76..a2a929b0c 100644
--- a/changelogs/client_server.rst
+++ b/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.