matrix-org / matrix-org/matrix-spec
`id_server` format is not documented
- 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
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