Matrix Decentralised HTTP Linking: Spec

Decentralised linking from the Web (HTTP contexts) to a matrix user or room.

Status: This is a proposed, draft specification for consideration by the matrix development community. This version was initially posted before any discussion or feedback.


A decentralised Web-to-Matrix linking protocol for the DNS-based types of matrix resource id (@user:server.tld, #room-alias:server.tld).



This specification defines decentralised linking from HTTP contexts to matrix resources such as @user and #room-alias that are based on DNS authority [^4] (clarified later).

For each such resource, this specification defines an HTTP(S) URL in which the authority part is the matrix server-name of the resource identifier.

To resolve such a URL, a client or user in a generic Web/HTTP context will connect directly to the authority responsible for the resource, following standard HTTP linking semantics.

This is in contrast to the use of “public” reception services such as the commonly used, where a client or user in a generic Web/HTTP context will connect first to that centralised service and so must rely on the operator of that service for integrity and availability.

Because a client resolves the URL through the DNS domain corresponding to the resource’s matrix server-name, the resolution is decentralised and not dependent on any central/public resource such as


Authority of a Room-Alias

This specification supports linking to a matrix room-alias. (For room-id, see subsection ‘[Out of Scope]’.)

In matrix, a room-alias is a non-unique pointer to a room, and is mutable: it can be changed to point at a different room, or it be removed. The DNS domain in the server-name part of a room-alias has the authority [^4] over the room-alias: the operator of this domain has control over what the room-alias points to. Linking to a room-alias therefore inherently means we authorise the matrix server named in it to resolve the room-alias to a room. It would be wrong to trust any other authority to do so, without verifying in some way against the correct authority. We can avoid always querying that authority if we cache the result for some (unspecified) period.


Examples often assume the following matrix server-name:


DNS-Authority Resources

This specification defines decentralised linking from HTTP contexts to matrix resources that use DNS authority (user, room-alias).

The following kinds of matrix resource identifier are based on a DNS domain name which acts as the authority [^4] over the resource.

We call any such identifier a DNS-MXID [^3].

The identifier grammar, and in particular the server-name part, is defined in the matrix spec. The server-name is commonly a DNS domain name. The wording and examples in this specification generally assume it is a DNS domain name.

Non-DNS Server-Names

The specification can also work with the other defined variants of server-name (an IP address, an optional port number). *(TODO: Refine the specification to clarify use with these variants, and add examples.)*

Out of Scope

This proposal does not intend to define a new method for addressing non-DNS-based identifiers, such as matrix decentralised room-ids (!room-id-hash) and any future non-DNS naming system(s) for users/rooms/spaces.

The matrix room-id (!room-id-hash) is out of scope. Although a :server-name part is sometimes present, it does not act as an authority in this kind of identifier.

Other forms of server-name, or of the whole identifiers, may be defined in future. For example, public-key-based identifiers for p2p-matrix. These are out of scope.


Reception Service

A matrix server MAY offer its own reception service, by advertising an end-point for it in .well-known/matrix/client (see ‘Well-known Advertisement’ section).

Examples of an advertised end-point:

The first example may suit the case where the main purpose of the domain is as a matrix server. The other examples may better suit the case where the domain is mainly used for other purposes.

The reception service is available on the advertised end-point. It serves a web-app that takes that represents a DNS-based matrix identifier (DNS-MXID) that the user wishes to resolve.

The input is passed to the web-app in the URL “fragment” part, after /#/, as in Unlike with, however, there may be no privacy reason to do so.

Examples of a complete URL:

Note: The functionality so far could be provided by a self-hosted instance of

Server-name suffix is optional for a DNS-MXID that matches this server-name. These two examples mean the same:

The no-suffix form is intended to be preferred where humans will read or write the reference.

(TODO: Maybe allow only one form. Don’t allow too much flexibility. KISS.)

Well-known Advertisement

The reception service end-point is available if advertised in The advertisement is a key:value pair where the key is (TODO:foo.reception.path?) and the value is the path of the API endpoint. Example:

  "foo.reception.path": "/to"

The meaning of this example is that the end-point would be at

(TODO: specify precisely... path starts with ‘/‘ and ends with no ‘/‘...)

(TODO: perhaps specify a flag that advertises whether server name-suffix is mandatory/optional/forbidden, if we decide more than one form is possible)

Client Behaviour

For constructing a link to a DNS-MXID, a matrix client SHOULD discover and use the reception service corresponding to the id, if one is advertised. For any other form of matrix id, or if no such service is advertised, the matrix client may use any suitable reception service for constructing the link.

Example: (TODO)

When parsing text that may contain links, a matrix client may wish to recognise, parse and treat specially any URL that is a DNS-MXID link.

Use the following procedure to determine whether a URL is in fact a DNS-MXID link:

When asked to follow a URL that may be a DNS-MXID link: a client SHOULD attempt the validation above, and if successful then use any method to resolve the resource from that identifier.

Example: given URL, a client SHOULD fetch and extract the advertised foo.reception.path field, and if that matches /butterfly then it can assume the URL is indeed a DNS-MXID link to, and use any method to resolve that.

Security Considerations


DNS-MXID: “DNS-based matrix identifier”: a matrix identifier anchored to a DNS domain name. Includes the identifier forms @user:domain, #room:domain, +space:domain. Does not include the form !room-id:domain (as the domain there is not anchoring the id).

reception service: an HTTP web service that, given a matrix id, helps the user to resolve and access the corresponding resource, such as by opening a matrix client with “deep linking” to the resource. Examples: and other instances of the software.


[MATRIX]: The project’s web site has the tag line “An open network for secure, decentralized communication” (emphasis mine). [M.TO-SITE]: The singular domain and the web-service it provides. [M.TO-CODE]: The reception service software that runs and can also be deployed on other domains. [M.TO-SYNTAX]: The use of URLs as a special syntax intended to recognised by matrix-aware software, as specified in [SPEC-TO]. [SPEC-ID]: Matrix spec v1.6: Identifier Grammar [SPEC-URI]: Matrix spec v1.6: Matrix URI scheme [SPEC-TO]: Matrix spec v1.6: navigation [^3]: In some other contexts, the term ‘MXID’ may imply only user identifiers. [^4]: The term “authority” is used in the DNS sense of meaning.



For engaging with discussion and development of the topic, please prefer the room linked here, rather than the blog comments facility:

Follow/Feedback/Contact: RSS feed · Fedi follow this blog: @julian​ · use the Cactus Comments box above · matrix me · Fedi follow me · email me · Donate: via Liberapay All posts © Julian Foad and licensed CC-BY-ND except quotes, translations, or where stated otherwise