diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 4b8e1d631cc..2c9a7da7524 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 00000000000..3395758dbe9 --- /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 3767c9b4790..6bff8ebbfff 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`.