Introduction
A Matrix user ID such as @alice:example.com names a server name, which is not always the host that runs the homeserver. So that a client can log in knowing only the ID, the Matrix specification
has it ask https://hostname/.well-known/matrix/client, where hostname comes from the server name. The file is JSON and gives the homeserver’s base URL. The specification (client-server API,
“Server Discovery”) uses RFC 8615 well-known URIs, and says the server hosting the file should offer CORS headers; since version 1.20 clients should follow 30x redirects, avoiding loops. A 404 means “ignore” (try something
else), any other failure or unparsable body means “fail and prompt the user”.
Structure
{
"m.homeserver": { "base_url": "https://matrix.example.com" },
"m.identity_server": { "base_url": "https://identity.example.com" },
"org.example.custom.property": { "app_url": "https://custom.app.example.org" }
}
| Key | Rule (Matrix specification, wellknown schema) |
|---|---|
m.homeserver | Required. An object with a required base_url: the base URL of the homeserver for client-server connections (a URI). Clients should check it by connecting to /_matrix/client/versions; the value may end in “/”, so consumers must handle both. |
m.identity_server | Optional. An object with a required base_url (validated with /_matrix/identity/v2). If the key is present but has no base_url, the client fails and prompts. |
| other keys | Additional keys “MUST follow the Java package naming convention, e.g. com.example.myapp.property”, so that names do not clash. |
In the explorer
The name client alone is far too common to claim, so a file is recognised as this one only (a) with the path .well-known/matrix/client (a file inside a folder, an archive or a container) or (b) by the names
matrix-client, matrix-client.json or matrix_client.json; and in either case only when it is a JSON object with an m.homeserver object. Anything else opens as before. The tree labels the keys; the Overview
shows the homeserver and identity server. A problem is a missing m.homeserver or base_url, a base_url that is not a URL, a key of the wrong type, or an additional key that is not shaped like a Java package name. Nothing is fetched, so the
homeserver is not contacted. Of the public sites tried, 10 served a client file and 10 a server file; one (privacytools) answered an HTML page for both and is not claimed.
Not described
Known, not yet covered
- Reference: the other discovery file,
/.well-known/matrix/support(contacts and a support page), the authentication discovery of newer Matrix versions, and the CORS requirements in full are named, not described. - Viewer: a bare file called
clientwith no path is not recognised, by design. - Viewer: additional keys are checked for the shape of a Java package name only, not for being registered anywhere.
Unknown
- Reference: whether a
base_urlmust use https: the schema says only “uri”.
Links
Reference
- Matrix client-server API: Well-known URIs – the specification
- Matrix server delegation – the federation counterpart, /.well-known/matrix/server
- RFC 8615 – Well-Known Uniform Resource Identifiers