Note that this is a simplified version of MSC1194.
Currently we do not have a reasonable route for a user to unbind/remove a 3PID from their account, particularly when deactivating their account. Users have an expectation to be able to do this, and thus we should have an API to provide it.
This is meant as a simple extension to the current APIs, and so this explicitly does not try and solve any existing usability concerns.
Add an id_server
param to POST /_matrix/client/r0/account/3pid/delete
API,
which matches the 3PID creation APIs.
The new id_server
parameter is optional and if missing the server will attempt
to unbind from the identity server used when originally binding the 3pid (if
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. If the homeserver
is unable to determine an id_server
to use, it should return no-support
for
the id_server_unbind_result
.
Example:
POST /_matrix/client/r0/account/3pid/delete HTTP/1.1
{
"medium": "email",
"address": "[email protected]",
"id_server": "https://matrix.org
}
HTTP/1.1 200 OK
{
"id_server_unbind_result": "success"
}
Add an id_server
param to POST /_matrix/client/r0/account/deactivate
API,
with the same semantics as above. This is used to unbind any bound threepids
from the given identity server.
Add POST /_matrix/identity/api/v1/3pid/unbind
with mxid
and threepid
fields.
The mxid
is the user's user_id
and threepid
is a dict with the usual
medium
and address
fields.
If the server returns a 400, 404 or 501 HTTP error code then the homeserver
should assume that the identity server doesn't support the /3pid/unbind
API, unless
it returns a specific matrix error response (i.e. the body is a JSON object with
error
and errcode
fields).
The identity server should authenticate the request in one of two ways:
- The request is signed by the homeserver which controls the
user_id
. - The request includes the
sid
andclient_secret
params (as per/bind
), which proves ownership of the given 3PID.
Example:
POST /_matrix/identity/api/v1/3pid/unbind HTTP/1.1
{
"mxid": "@foobar:example.com",
"threepid": {
"medium": "email",
"address": "[email protected]"
}
}
HTTP/1.1 200 OK
{}
A homeserver can unbind any 3PID associated with one of its users, and specifically does not require a re-validation of control of the 3PID. This means that users have to trust that their homeserver will not arbitrarily remove valid 3PIDs, however users must already trust their homeserver to a large extent. The flip side is that this provides a mechanism for homeservers and users to remove 3PIDs directed at their user IDs that they no longer (or never did) have control over.
Removing a 3PID does not require user interactive auth (UIA), which opens a potential attack whereby a logged in device can remove all associated 3PIDs and then log out all devices. If the user has forgotten their password they would no longer be able to reset their password via a 3PID (e.g. email), resulting in losing access to their account. However, given that clients and servers have implemented these APIs in the wild this is considered a sufficient edge case that adding UIA is unlikely to be worthwhile.