matrix-org / matrix-org/matrix-spec

`id_server` format is not documented

Open
#2,056 0 comments 0 reactions 0 assignees View on GitHub
clarification
Dominant language
HTML
Stars
330
Forks
150
Avg merge
2h 21m
Merged PRs (30d)
3

Description

**Link to problem area**:

Login types involving 3PIDs:

- [`m.login.email.identity`](https://spec.matrix.org/v1.13/client-server-api/#email-based-identity--homeserver)
- [`m.login.msisdn`](https://spec.matrix.org/v1.13/client-server-api/#phone-numbermsisdn-based-identity--homeserver)

Endpoints involving 3PIDs:

- [`POST /_matrix/client/v3/account/deactivate`](https://spec.matrix.org/v1.13/client-server-api/#post_matrixclientv3accountdeactivate)
- [`POST /_matrix/client/v3/account/password/email/requestToken`](https://spec.matrix.org/v1.13/client-server-api/#post_matrixclientv3accountpasswordemailrequesttoken)
- [`POST /_matrix/client/v3/account/password/msisdn/requestToken`](https://spec.matrix.org/v1.13/client-server-api/#post_matrixclientv3accountpasswordmsisdnrequesttoken)
- [`POST /_matrix/client/v3/register/email/requestToken`](https://spec.matrix.org/v1.13/client-server-api/#post_matrixclientv3registeremailrequesttoken)
- [`POST /_matrix/client/v3/register/msisdn/requestToken`](https://spec.matrix.org/v1.13/client-server-api/#post_matrixclientv3registermsisdnrequesttoken)
- [`POST /_matrix/client/v3/account/3pid`](https://spec.matrix.org/v1.13/client-server-api/#post_matrixclientv3account3pid)
- [`POST /_matrix/client/v3/account/3pid/bind`](https://spec.matrix.org/v1.13/client-server-api/#post_matrixclientv3account3pidbind)
- [`POST /_matrix/client/v3/account/3pid/unbind`](https://spec.matrix.org/v1.13/client-server-api/#post_matrixclientv3account3pidunbind)
- [`POST /_matrix/client/v3/account/3pid/delete`](https://spec.matrix.org/v1.13/client-server-api/#post_matrixclientv3account3piddelete)
- [`POST /_matrix/client/v3/account/3pid/email/requestToken`](https://spec.matrix.org/v1.13/client-server-api/#post_matrixclientv3account3pidemailrequesttoken)
- [`POST /_matrix/client/v3/account/3pid/msisdn/requestToken`](https://spec.matrix.org/v1.13/client-server-api/#post_matrixclientv3account3pidmsisdnrequesttoken)
- [`POST /_matrix/client/v3/createRoom`](https://spec.matrix.org/v1.13/client-server-api/#post_matrixclientv3createroom)
- [`POST /_matrix/client/v3/rooms/{roomId}/invite`](https://spec.matrix.org/v1.13/client-server-api/#thirdparty_post_matrixclientv3roomsroomidinvite)

**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](https://spec.matrix.org/v1.13/appendices/#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: https://github.com/matrix-org/synapse/pull/9802#discussion_r613172343
- 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](https://spec.matrix.org/v1.13/client-server-api/#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

Contributor guide

Open the contributing guide

Research direction

Start with the linked client-server API sections for 3PID login, account, registration, room creation, and invitation flows. Compare their current wording with the referenced Synapse, Element Web, and matrix-js-sdk behavior; done means documenting where id_server comes from, its authority-only format, and how homeservers use it consistently.

Written by the indexing model from the issue text.

Assessment

Domain
documentation, networking
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.