From 185c564a13797f511fc42ae43154fac8f28fe552 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travpc@gmail.com>
Date: Wed, 4 Sep 2019 16:33:54 -0600
Subject: [PATCH] Spec client-server IS unbind API

As per [MSC2140](https://github.com/matrix-org/matrix-doc/pull/2140)

Note: this modifies the endpoint in MSC2140 to be more in line with the remainder of the proposal.
---
 api/client-server/administrative_contact.yaml | 64 +++++++++++++++++++
 .../client_server/newsfragments/2282.new      |  1 +
 proposals/2140-terms-of-service-2.md          |  3 +-
 3 files changed, 67 insertions(+), 1 deletion(-)
 create mode 100644 changelogs/client_server/newsfragments/2282.new

diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml
index 4b8e1d631..2c9a7da75 100644
--- a/api/client-server/administrative_contact.yaml
+++ b/api/client-server/administrative_contact.yaml
@@ -234,6 +234,70 @@ paths:
               - id_server_unbind_result
       tags:
         - User data
+  "/account/3pid/unbind":
+    post:
+      summary: Removes a user's third party identifier from an identity server.
+      description: |-
+        Removes a user's third party identifier from the provided identity server.
+        This should not cause an unbind from the homeserver (as ``/3pid/delete``
+        would) and should only affect the identity server.
+
+        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.
+      operationId: unbind3pidFromAccount
+      security:
+        - accessToken: []
+      parameters:
+        - in: body
+          name: body
+          schema:
+            type: object
+            properties:
+              id_server:
+                type: string
+                description: |-
+                    The identity server to unbind from. If not provided, the homeserver
+                    MUST use the ``id_server`` the identifier was added through. If the
+                    homeserver does not know the original ``id_server``, it MUST return
+                    a ``id_server_unbind_result`` of ``no-support``.
+                example: "example.org"
+              medium:
+                type: string
+                description: The medium of the third party identifier being removed.
+                enum: ["email", "msisdn"]
+                example: "email"
+              address:
+                type: string
+                description: The third party address being removed.
+                example: "example@example.org"
+            required: ['medium', 'address']
+      responses:
+        200:
+          description: |-
+            The identity server has disassociated the third party identifier from the
+            user.
+          schema:
+            type: object
+            properties:
+              id_server_unbind_result:
+                type: string
+                enum:
+                  # XXX: I don't know why, but the order matters here so that "no-support"
+                  # doesn't become "no- support" by the renderer.
+                  - "no-support"
+                  - "success"
+                description: |-
+                  An indicator as to whether or not the identity server was able to unbind
+                  the 3PID. ``success`` indicates that the identity server has unbound the
+                  identifier whereas ``no-support`` indicates that the identity server
+                  refuses to support the request or the homeserver was not able to determine
+                  an identity server to unbind from.
+                example: "success"
+            required:
+              - id_server_unbind_result
+      tags:
+        - User data
   "/account/3pid/email/requestToken":
     post:
       summary: Begins the validation process for an email address for association with the user's account.
diff --git a/changelogs/client_server/newsfragments/2282.new b/changelogs/client_server/newsfragments/2282.new
new file mode 100644
index 000000000..3395758db
--- /dev/null
+++ b/changelogs/client_server/newsfragments/2282.new
@@ -0,0 +1 @@
+Add ``POST /account/3pid/unbind`` for removing a 3PID from an identity server.
diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md
index 3767c9b47..6bff8ebbf 100644
--- a/proposals/2140-terms-of-service-2.md
+++ b/proposals/2140-terms-of-service-2.md
@@ -271,7 +271,8 @@ A client uses this client/server API endpoint to request that the Homeserver
 removes the given 3PID from the given Identity Server, or all Identity Servers.
 Takes the same parameters as
 `POST /_matrix/client/r0/account/3pid/delete`, ie. `id_server`, `medium`,
-`address` and the newly added `id_access_token`.
+`address`. Similar to the other unbind endpoints, this endpoint does not
+require an `id_access_token` because the homeserver can only unbind.
 
 Returns the same as `POST /_matrix/client/r0/account/3pid/delete`.