Spec 3PID unbind API

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

Implementation proof: 
* https://github.com/matrix-org/synapse/pull/4982
* https://github.com/matrix-org/sydent/pull/160

The only alteration made which differs from the proposal is clarity on how to handle homeservers not knowing the `id_server`. All other differences are unintentional.

api/client-server/administrative_contact.yaml

@@ -163,6 +163,14 @@ paths:
           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.
@@ -180,7 +188,24 @@ paths:
             user.
           schema:
             type: object
-            properties: {}
+            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 homeserver was able to unbind
+                  the 3PID from the identity server. ``success`` indicates that the
+                  indentity 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":

api/client-server/registration.yaml

@@ -524,13 +524,39 @@ paths:
                 description: |-
                   Additional authentication information for the user-interactive authentication API.
                 "$ref": "definitions/auth_data.yaml"
+              id_server:
+                type: string
+                description: |-
+                  The identity server to unbind all of the user's 3PIDs from.
+                  If not provided, the homeserver MUST use the ``id_server``
+                  that was originally use to bind each identifier. If the
+                  homeserver does not know which ``id_server`` that was,
+                  it must return an ``id_server_unbind_result`` of
+                  ``no-support``.
+                example: "example.org"
       responses:
         200:
           description: The account has been deactivated.
-          examples:
-            application/json: {}
           schema:
             type: object
+            properties:
+              id_server_unbind_result:
+                type: string
+                enum:
+                  - "success"
+                  - "no-support"
+                description: |-
+                  An indicator as to whether or not the homeserver was able to unbind
+                  the user's 3PIDs from the identity server(s). ``success`` indicates
+                  that all identifiers have been unbound from the identity server while
+                  ``no-support`` indicates that one or more identifiers failed to unbind
+                  due to the identity server refusing the request or the homeserver
+                  being unable to determine an identity server to unbind from. This
+                  must be ``success`` if the homeserver has no identifiers to unbind
+                  for the user.
+                example: "success"
+            required:
+              - id_server_unbind_result
         401:
           description: |-
             The homeserver requires additional authentication information.

api/identity/associations.yaml

@@ -201,3 +201,86 @@ paths:
             }
           schema:
             $ref: "../client-server/definitions/errors/error.yaml"
+  "/3pid/unbind":
+    post:
+      summary: Remove an association between a session and a Matrix user ID.
+      description: |-
+        Remove an association between a session and a Matrix user ID.
+
+        Future calls to ``/lookup`` for any of the session's 3pids will not
+        return the removed association.
+
+        The identity server should authenticate the request in one of two
+        ways:
+
+        1. The request is signed by the homeserver which controls the ``user_id``.
+        2. The request includes the ``sid`` and ``client_secret`` parameters,
+           as per ``/3pid/bind``, which proves ownership of the 3PID.
+
+        If this endpoint returns a JSON Matrix error, that error should be passed
+        through to the client requesting an unbind through a homeserver, if the
+        homeserver is acting on behalf of a client.
+      operationId: unbind
+      parameters:
+        - in: body
+          name: body
+          schema:
+            type: object
+            example: {
+              "sid": "1234",
+              "client_secret": "monkeys_are_GREAT",
+              "mxid": "@ears:example.org",
+              "threepid": {
+                "medium": "email",
+                "address": "monkeys_have_ears@example.org"
+              }
+            }
+            properties:
+              sid:
+                type: string
+                description: The Session ID generated by the ``requestToken`` call.
+              client_secret:
+                type: string
+                description: The client secret passed to the ``requestToken`` call.
+              mxid:
+                type: string
+                description: The Matrix user ID to remove from the 3pids.
+              threepid:
+                type: object
+                title: 3PID
+                description: |-
+                  The 3PID to remove. Must match the 3PID used to generate the session
+                  if using ``sid`` and ``client_secret`` to authenticate this request.
+                properties:
+                  medium:
+                    type: string
+                    description: |-
+                      A medium from the `3PID Types`_ Appendix, matching the medium
+                      of the identifier to unbind.
+                  address:
+                    type: string
+                    description: The 3PID address to remove.
+                required: ['medium', 'address']
+            required: ["threepid", "mxid"]
+      responses:
+        200:
+          description: The association was successfully removed.
+          examples:
+            application/json: {}
+          schema:
+            type: object
+        400:
+          description: |-
+            If the response body is not a JSON Matrix error, the identity server
+            does not support unbinds. If a JSON Matrix error is in the response
+            body, the requesting party should respect the error.
+        404:
+          description: |-
+            If the response body is not a JSON Matrix error, the identity server
+            does not support unbinds. If a JSON Matrix error is in the response
+            body, the requesting party should respect the error.
+        501:
+          description: |-
+            If the response body is not a JSON Matrix error, the identity server
+            does not support unbinds. If a JSON Matrix error is in the response
+            body, the requesting party should respect the error.

changelogs/client_server/newsfragments/2046.feature

@@ -0,0 +1 @@
+Add ``id_server`` to ``/deactivate`` and ``/3pid/delete`` endpoints to unbind from a specific identity server.

changelogs/identity_service/newsfragments/2046.new

@@ -0,0 +1 @@
+Add ``/3pid/unbind`` for removing 3PIDs.

proposals/1915-unbind-identity-server-param.md

@@ -27,7 +27,9 @@ known by the homeserver).
 The 200 response is a JSON object with an `id_server_unbind_result` field whose
 value is either `success` or `no-support`, where the latter indicates that the
 identity server (IS) does not support unbinding 3PIDs directly. If the identity
-server returns an error then that should be returned to the client.
+server returns an error then that should be returned to the client. If the homeserver
+is unable to determine an `id_server` to use, it should return `no-support` for
+the `id_server_unbind_result`.
 
 Example: