id_server format is not documented

[zecakeh]

Link to problem area:

Login types involving 3PIDs:

• m.login.email.identity
• m.login.msisdn

Endpoints involving 3PIDs:

• POST /_matrix/client/v3/account/deactivate
• POST /_matrix/client/v3/account/password/email/requestToken
• POST /_matrix/client/v3/account/password/msisdn/requestToken
• POST /_matrix/client/v3/register/email/requestToken
• POST /_matrix/client/v3/register/msisdn/requestToken
• POST /_matrix/client/v3/account/3pid
• POST /_matrix/client/v3/account/3pid/bind
• POST /_matrix/client/v3/account/3pid/unbind
• POST /_matrix/client/v3/account/3pid/delete
• POST /_matrix/client/v3/account/3pid/email/requestToken
• POST /_matrix/client/v3/account/3pid/msisdn/requestToken
• POST /_matrix/client/v3/createRoom
• POST /_matrix/client/v3/rooms/{roomId}/invite

Issue

It is not documented where this string can be found by clients, and how homeservers are supposed to use it.

Usually in the examples it looks like a server name, and its format has several descriptions which match more or less that assumption:

url of identity server authed with, e.g. 'matrix.org:8090'

The hostname of the identity server to communicate with. May optionally include a port.

The hostname+port of the identity server.

However in practice, this string is actually a URL starting at the authority (i.e. with the http(s):// part removed):

• Synapse expects a server name and optionally a path: Sanity check identity server passed to bind/unbind. synapse#9802 (comment)
• It is then used by prepending the scheme, and appending the IS API endpoint path, for example: https://github.com/element-hq/synapse/blob/39bd6e2c167dd2c8b1b46ea449f34ecf072fd614/synapse/handlers/identity.py#L201
• In Element Web it can be produced with the identity service's base URL found at the well-known URI, and by removing the scheme: https://github.com/element-hq/element-web/blob/13913ba8b20f3d344aac77f2d0c8fdaf1aceb55d/src/utils/dm/startDm.ts#L70
• Using this method from the matrix-js-sdk: https://github.com/matrix-org/matrix-js-sdk/blob/5babcaf4b34d48bf15775f7fbb5168883a0831f9/src/client.ts#L8045