Introduction
Matrix homeservers talk to each other over the federation (server-server) API. A homeserver is identified by a server name, and the name does not have to be the host that serves the traffic. The server-server
API (“Resolving server names”) says that when the hostname is not an IP literal and the name has no explicit port, a server makes an HTTPS request to https://<hostname>/.well-known/matrix/server and reads one key
from the JSON answer: m.server, the host and optional port to connect to instead. Redirects should be followed (avoiding loops); an invalid response (bad JSON, missing properties, a non-200 answer) sends the server to the
next resolution step. Responses should be cached, with a recommended default of 24 hours, a maximum of 48, and errors for up to an hour.
Structure
{
"m.server": "delegated.example.com:1234"
}
| Key | Rule (Matrix server-server API, wellknown) |
|---|---|
m.server | A string: the server name to delegate server-server communication to, with an optional port. It is parsed as <delegated_hostname>[:<delegated_port>] and uses the same grammar as server names. With no port, an SRV record
_matrix-fed._tcp.<hostname> is looked up (version 1.8 and later); the steps that follow when there is none are in the specification and are not described here. |
The response should have Content-Type: application/json, but parsers “should assume that the body is JSON regardless of type”.
In the explorer
A file is recognised here only with the path .well-known/matrix/server or by the names matrix-server, matrix-server.json or matrix_server.json (a bare server is too common to claim), and only when it is a JSON object with an
m.server string. The tree labels the key; the Overview shows the delegated server. A problem is a missing m.server, a value that is not hostname[:port] (a scheme or a path), or a port outside 1 to 65535. Nothing is fetched, so the SRV record
and the certificate are not looked up. Other files with these names open as before.
Not described
Known, not yet covered
- Reference: the rest of the server-name resolution (IP literals, SRV records, the deprecated
_matrix._tcprecord, the Host header and certificate rules) and the server name grammar are summarised, not described in full. - Viewer: the host name is checked for shape, not against the full server-name grammar of the Matrix appendices.
Unknown
- Reference: none known.
Links
Reference
- Matrix server-server API: Resolving server names – the specification
- Matrix client discovery – the client counterpart, /.well-known/matrix/client
- RFC 8615 – Well-Known Uniform Resource Identifiers