Server-Server API

Matrix homeservers use the Federation APIs (also known as server-server APIs) to communicate with each other. Homeservers use these APIs to push messages to each other in real-time, to retrieve historic messages from each other, and to query profile and presence information about users on each other’s servers.

The APIs are implemented using HTTPS requests between each of the servers. These HTTPS requests are strongly authenticated using public key signatures at the TLS transport layer and using public key signatures in HTTP Authorization headers at the HTTP layer.

There are three main kinds of communication that occur between homeservers:

Persisted Data Units (PDUs): These events are broadcast from one homeserver to any others that have joined the same room (identified by Room ID). They are persisted in long-term storage and record the history of messages and state for a room.

Like email, it is the responsibility of the originating server of a PDU to deliver that event to its recipient servers. However PDUs are signed using the originating server’s private key so that it is possible to deliver them through third-party servers.

Ephemeral Data Units (EDUs): These events are pushed between pairs of homeservers. They are not persisted and are not part of the history of a room, nor does the receiving homeserver have to reply to them.

Queries: These are single request/response interactions between a given pair of servers, initiated by one side sending an HTTPS GET request to obtain some information, and responded by the other. They are not persisted and contain no long-term significant history. They simply request a snapshot state at the instant the query is made.

EDUs and PDUs are further wrapped in an envelope called a Transaction, which is transferred from the origin to the destination homeserver using an HTTPS PUT request.

API standards

The mandatory baseline for server-server communication in Matrix is exchanging JSON objects over HTTPS APIs. More efficient transports may be specified in future as optional extensions.

All POST and PUT endpoints require the requesting server to supply a request body containing a (potentially empty) JSON object. Requesting servers should supply a Content-Type header of application/json for all requests with JSON bodies, but this is not required.

Similarly, all endpoints in this specification require the destination server to return a JSON object. Servers must include a Content-Type header of application/json for all JSON responses.

All JSON data, in requests or responses, must be encoded using UTF-8.

TLS

Server-server communication must take place over HTTPS.

The destination server must provide a TLS certificate signed by a known Certificate Authority.

Requesting servers are ultimately responsible for determining the trusted Certificate Authorities, however are strongly encouraged to rely on the operating system’s judgement. Servers can offer administrators a means to override the trusted authorities list. Servers can additionally skip the certificate validation for a given whitelist of domains or netmasks for the purposes of testing or in networks where verification is done elsewhere, such as with .onion addresses.

Servers should respect SNI when making requests where possible: a SNI should be sent for the certificate which is expected, unless that certificate is expected to be an IP address in which case SNI is not supported and should not be sent.

Servers are encouraged to make use of the Certificate Transparency project.

Unsupported endpoints

If a request for an unsupported (or unknown) endpoint is received then the server must respond with a 404 M_UNRECOGNIZED error.

Similarly, a 405 M_UNRECOGNIZED error is used to denote an unsupported method to a known endpoint.

Server discovery

Resolving server names

Each Matrix homeserver is identified by a server name consisting of a hostname and an optional port, as described by the grammar. Where applicable, a delegated server name uses the same grammar.

Server names are resolved to an IP address and port to connect to, and have various conditions affecting which certificates and Host headers to send. The process overall is as follows:

1. If the hostname is an IP literal, then that IP address should be used, together with the given port number, or 8448 if no port is given. The target server must present a valid certificate for the IP address. The Host header in the request should be set to the server name, including the port if the server name included one.

2. If the hostname is not an IP literal, and the server name includes an explicit port, resolve the hostname to an IP address using CNAME, AAAA or A records. Requests are made to the resolved IP address and given port with a Host header of the original server name (with port). The target server must present a valid certificate for the hostname.

3. If the hostname is not an IP literal, a regular HTTPS request is made to https://<hostname>/.well-known/matrix/server, expecting the schema defined later in this section. 30x redirects should be followed, however redirection loops should be avoided. Responses (successful or otherwise) to the /.well-known endpoint should be cached by the requesting server. Servers should respect the cache control headers present on the response, or use a sensible default when headers are not present. The recommended sensible default is 24 hours. Servers should additionally impose a maximum cache time for responses: 48 hours is recommended. Errors are recommended to be cached for up to an hour, and servers are encouraged to exponentially back off for repeated failures. The schema of the /.well-known request is later in this section. If the response is invalid (bad JSON, missing properties, non-200 response, etc), skip to step 4. If the response is valid, the m.server property is parsed as <delegated_hostname>[:<delegated_port>] and processed as follows:

   • If <delegated_hostname> is an IP literal, then that IP address should be used together with the <delegated_port> or 8448 if no port is provided. The target server must present a valid TLS certificate for the IP address. Requests must be made with a Host header containing the IP address, including the port if one was provided.
   • If <delegated_hostname> is not an IP literal, and <delegated_port> is present, an IP address is discovered by looking up CNAME, AAAA or A records for <delegated_hostname>. The resulting IP address is used, alongside the <delegated_port>. Requests must be made with a Host header of <delegated_hostname>:<delegated_port>. The target server must present a valid certificate for <delegated_hostname>.
   • If <delegated_hostname> is not an IP literal and no <delegated_port> is present, an SRV record is looked up for _matrix._tcp.<delegated_hostname>. This may result in another hostname (to be resolved using AAAA or A records) and port. Requests should be made to the resolved IP address and port with a Host header containing the <delegated_hostname>. The target server must present a valid certificate for <delegated_hostname>.
   • If no SRV record is found, an IP address is resolved using CNAME, AAAA or A records. Requests are then made to the resolve IP address and a port of 8448, using a Host header of <delegated_hostname>. The target server must present a valid certificate for <delegated_hostname>.

4. If the /.well-known request resulted in an error response, a server is found by resolving an SRV record for _matrix._tcp.<hostname>. This may result in a hostname (to be resolved using AAAA or A records) and port. Requests are made to the resolved IP address and port, using 8448 as a default port, with a Host header of <hostname>. The target server must present a valid certificate for <hostname>.

5. If the /.well-known request returned an error response, and the SRV record was not found, an IP address is resolved using CNAME, AAAA and A records. Requests are made to the resolved IP address using port 8448 and a Host header containing the <hostname>. The target server must present a valid certificate for <hostname>.

{
  "m.server": "delegated.example.com:1234"
}

Server implementation

{
  "server": {
    "name": "My_Homeserver_Implementation",
    "version": "ArbitraryVersionNumber"
  }
}

Retrieving server keys

Each homeserver publishes its public keys under /_matrix/key/v2/server. Homeservers query for keys by either getting /_matrix/key/v2/server directly or by querying an intermediate notary server using a /_matrix/key/v2/query/{serverName} API. Intermediate notary servers query the /_matrix/key/v2/server API on behalf of another server and sign the response with their own key. A server may query multiple notary servers to ensure that they all report the same public keys.

This approach is borrowed from the Perspectives Project, but modified to include the NACL keys and to use JSON instead of XML. It has the advantage of avoiding a single trust-root since each server is free to pick which notary servers they trust and can corroborate the keys returned by a given notary server by querying other servers.

Publishing Keys

Homeservers publish their signing keys in a JSON object at /_matrix/key/v2/server/{key_id}. The response contains a list of verify_keys that are valid for signing federation requests made by the homeserver and for signing events. It contains a list of old_verify_keys which are only valid for signing events.

{
  "old_verify_keys": {
    "ed25519:0ldk3y": {
      "expired_ts": 1532645052628,
      "key": "VGhpcyBzaG91bGQgYmUgeW91ciBvbGQga2V5J3MgZWQyNTUxOSBwYXlsb2FkLg"
    }
  },
  "server_name": "example.org",
  "signatures": {
    "example.org": {
      "ed25519:auto2": "VGhpcyBzaG91bGQgYWN0dWFsbHkgYmUgYSBzaWduYXR1cmU"
    }
  },
  "valid_until_ts": 1652262000000,
  "verify_keys": {
    "ed25519:abc123": {
      "key": "VGhpcyBzaG91bGQgYmUgYSByZWFsIGVkMjU1MTkgcGF5bG9hZA"
    }
  }
}

Querying Keys Through Another Server

Servers may query another server’s keys through a notary server. The notary server may be another homeserver. The notary server will retrieve keys from the queried servers through use of the /_matrix/key/v2/server API. The notary server will additionally sign the response from the queried server before returning the results.

Notary servers can return keys for servers that are offline or having issues serving their own keys by using cached responses. Keys can be queried from multiple servers to mitigate against DNS spoofing.

{
  "server_keys": {
    "example.org": {
      "ed25519:abc123": {
        "minimum_valid_until_ts": 1234567890
      }
    }
  }
}

{
  "server_keys": [
    {
      "old_verify_keys": {
        "ed25519:0ldk3y": {
          "expired_ts": 1532645052628,
          "key": "VGhpcyBzaG91bGQgYmUgeW91ciBvbGQga2V5J3MgZWQyNTUxOSBwYXlsb2FkLg"
        }
      },
      "server_name": "example.org",
      "signatures": {
        "example.org": {
          "ed25519:abc123": "VGhpcyBzaG91bGQgYWN0dWFsbHkgYmUgYSBzaWduYXR1cmU"
        },
        "notary.server.com": {
          "ed25519:010203": "VGhpcyBpcyBhbm90aGVyIHNpZ25hdHVyZQ"
        }
      },
      "valid_until_ts": 1652262000000,
      "verify_keys": {
        "ed25519:abc123": {
          "key": "VGhpcyBzaG91bGQgYmUgYSByZWFsIGVkMjU1MTkgcGF5bG9hZA"
        }
      }
    }
  ]
}

{
  "server_keys": [
    {
      "old_verify_keys": {
        "ed25519:0ldk3y": {
          "expired_ts": 1532645052628,
          "key": "VGhpcyBzaG91bGQgYmUgeW91ciBvbGQga2V5J3MgZWQyNTUxOSBwYXlsb2FkLg"
        }
      },
      "server_name": "example.org",
      "signatures": {
        "example.org": {
          "ed25519:abc123": "VGhpcyBzaG91bGQgYWN0dWFsbHkgYmUgYSBzaWduYXR1cmU"
        },
        "notary.server.com": {
          "ed25519:010203": "VGhpcyBpcyBhbm90aGVyIHNpZ25hdHVyZQ"
        }
      },
      "valid_until_ts": 1652262000000,
      "verify_keys": {
        "ed25519:abc123": {
          "key": "VGhpcyBzaG91bGQgYmUgYSByZWFsIGVkMjU1MTkgcGF5bG9hZA"
        }
      }
    }
  ]
}

Authentication

Request Authentication

Every HTTP request made by a homeserver is authenticated using public key digital signatures. The request method, target and body are signed by wrapping them in a JSON object and signing it using the JSON signing algorithm. The resulting signatures are added as an Authorization header with an auth scheme of X-Matrix. Note that the target field should include the full path starting with /_matrix/..., including the ? and any query parameters if present, but should not include the leading https:, nor the destination server’s hostname.

Step 1 sign JSON:

{
    "method": "GET",
    "uri": "/target",
    "origin": "origin.hs.example.com",
    "destination": "destination.hs.example.com",
    "content": <JSON-parsed request body>,
    "signatures": {
        "origin.hs.example.com": {
            "ed25519:key1": "ABCDEF..."
        }
    }
}

The server names in the JSON above are the server names for each homeserver involved. Delegation from the server name resolution section above do not affect these - the server names from before delegation would take place are used. This same condition applies throughout the request signing process.

Step 2 add Authorization header:

GET /target HTTP/1.1
Authorization: X-Matrix origin="origin.hs.example.com",destination="destination.hs.example.com",key="ed25519:key1",sig="ABCDEF..."
Content-Type: application/json

<JSON-encoded request body>

Example python code:

def authorization_headers(origin_name, origin_signing_key,
                          destination_name, request_method, request_target,
                          content=None):
    request_json = {
         "method": request_method,
         "uri": request_target,
         "origin": origin_name,
         "destination": destination_name,
    }

    if content is not None:
        # Assuming content is already parsed as JSON
        request_json["content"] = content

    signed_json = sign_json(request_json, origin_name, origin_signing_key)

    authorization_headers = []

    for key, sig in signed_json["signatures"][origin_name].items():
        authorization_headers.append(bytes(
            "X-Matrix origin=\"%s\",destination=\"%s\",key=\"%s\",sig=\"%s\"" % (
                origin_name, destination_name, key, sig,
            )
        ))

    return ("Authorization", authorization_headers[0])

The format of the Authorization header is given in RFC 7235. In summary, the header begins with authorization scheme X-Matrix, followed by one or more spaces, followed by a comma-separated list of parameters written as name=value pairs. The names are case insensitive and order does not matter. The values must be enclosed in quotes if they contain characters that are not allowed in tokens, as defined in RFC 7230; if a value is a valid token, it may or may not be enclosed in quotes. Quoted values may include backslash-escaped characters. When parsing the header, the recipient must unescape the characters. That is, a backslash-character pair is replaced by the character that follows the backslash.

For compatibility with older servers, the sender should

• only include one space after X-Matrix,
• only use lower-case names, and
• avoid using backslashes in parameter values.

For compatibility with older servers, the recipient should allow colons to be included in values without requiring the value to be enclosed in quotes.

The authorization parameters to include are:

• origin: the server name of the sending server. This is the same as the origin field from JSON described in step 1.
• destination: [Added in v1.3] the server name of the receiving sender. This is the same as the destination field from the JSON described in step 1. For compatibility with older servers, recipients should accept requests without this parameter, but MUST always send it. If this property is included, but the value does not match the receiving server’s name, the receiving server must deny the request with an HTTP status code 401 Unauthorized.
• key: the ID, including the algorithm name, of the sending server’s key used to sign the request.
• signature: the signature of the JSON as calculated in step 1.

Unknown parameters are ignored.

Response Authentication

Responses are authenticated by the TLS server certificate. A homeserver should not send a request until it has authenticated the connected server to avoid leaking messages to eavesdroppers.

Client TLS Certificates

Requests are authenticated at the HTTP layer rather than at the TLS layer because HTTP services like Matrix are often deployed behind load balancers that handle the TLS and these load balancers make it difficult to check TLS client certificates.

A homeserver may provide a TLS client certificate and the receiving homeserver may check that the client certificate matches the certificate of the origin homeserver.

Transactions

The transfer of EDUs and PDUs between homeservers is performed by an exchange of Transaction messages, which are encoded as JSON objects, passed over an HTTP PUT request. A Transaction is meaningful only to the pair of homeservers that exchanged it; they are not globally-meaningful.

Transactions are limited in size; they can have at most 50 PDUs and 100 EDUs.

{
  "origin": "matrix.org",
  "origin_server_ts": 1234567890,
  "pdus": [
    {
      "content": {
        "see_room_version_spec": "The event format changes depending on the room version."
      },
      "room_id": "!somewhere:example.org",
      "type": "m.room.minimal_pdu"
    }
  ]
}

{
  "pdus": {
    "$failed_event:example.org": {
      "error": "You are not allowed to send a message to this room."
    },
    "$successful_event:example.org": {}
  }
}

PDUs

Each PDU contains a single Room Event which the origin server wants to send to the destination.

The prev_events field of a PDU identifies the “parents” of the event, and thus establishes a partial ordering on events within the room by linking them into a Directed Acyclic Graph (DAG). The sending server should populate this field with all of the events in the room for which it has not yet seen a child - thus demonstrating that the event comes after all other known events.

For example, consider a room whose events form the DAG shown below. A server creating a new event in this room should populate the new event’s prev_events field with both E4 and E6, since neither event yet has a child:

E1
^
|
E2 <--- E5
^       ^
|       |
E3      E6
^
|
E4

For a full schema of what a PDU looks like, see the room version specification.

Checks performed on receipt of a PDU

Whenever a server receives an event from a remote server, the receiving server must ensure that the event:

1. Is a valid event, otherwise it is dropped. For an event to be valid, it must contain a room_id, and it must comply with the event format of that room version.
2. Passes signature checks, otherwise it is dropped.
3. Passes hash checks, otherwise it is redacted before being processed further.
4. Passes authorization rules based on the event’s auth events, otherwise it is rejected.
5. Passes authorization rules based on the state before the event, otherwise it is rejected.
6. Passes authorization rules based on the current state of the room, otherwise it is “soft failed”.

Further details of these checks, and how to handle failures, are described below.

The Signing Events section has more information on which hashes and signatures are expected on events, and how to calculate them.

Definitions

Required Power Level

A given event type has an associated required power level. This is given by the current m.room.power_levels event. The event type is either listed explicitly in the events section or given by either state_default or events_default depending on if the event is a state event or not.

Invite Level, Kick Level, Ban Level, Redact Level

The levels given by the invite, kick, ban, and redact properties in the current m.room.power_levels state. The invite level defaults to 0 if unspecified. The kick level, ban level and redact level each default to 50 if unspecified.

Target User

For an m.room.member state event, the user given by the state_key of the event.

Authorization rules

The rules governing whether an event is authorized depends on a set of state. A given event is checked multiple times against different sets of state, as specified above. Each room version can have a different algorithm for how the rules work, and which rules are applied. For more detailed information, please see the room version specification.

Auth events selection

The auth_events field of a PDU identifies the set of events which give the sender permission to send the event. The auth_events for the m.room.create event in a room is empty; for other events, it should be the following subset of the room state:

• The m.room.create event.

• The current m.room.power_levels event, if any.

• The sender’s current m.room.member event, if any.

• If type is m.room.member:

  • The target’s current m.room.member event, if any.
  • If membership is join or invite, the current m.room.join_rules event, if any.
  • If membership is invite and content contains a third_party_invite property, the current m.room.third_party_invite event with state_key matching content.third_party_invite.signed.token, if any.
  • If content.join_authorised_via_users_server is present, and the room version supports restricted rooms, then the m.room.member event with state_key matching content.join_authorised_via_users_server.

Rejection

If an event is rejected it should neither be relayed to clients nor be included as a prev event in any new events generated by the server. Subsequent events from other servers that reference rejected events should be allowed if they still pass the auth rules. The state used in the checks should be calculated as normal, except not updating with the rejected event where it is a state event.

If an event in an incoming transaction is rejected, this should not cause the transaction request to be responded to with an error response.

Soft failure

When the homeserver receives a new event over federation it should also check whether the event passes auth checks based on the current state of the room (as well as based on the state at the event). If the event does not pass the auth checks based on the current state of the room (but does pass the auth checks based on the state at that event) it should be “soft failed”.

When an event is “soft failed” it should not be relayed to the client nor be referenced by new events created by the homeserver (i.e. they should not be added to the server’s list of forward extremities of the room). Soft failed events are otherwise handled as usual.

Example

As an example consider the event graph:

  A
 /
B

where B is a ban of a user X. If the user X tries to set the topic by sending an event C while evading the ban:

  A
 / \
B   C

servers that receive C after B should soft fail event C, and so will neither relay C to its clients nor send any events referencing C.

If later another server sends an event D that references both B and C (this can happen if it received C before B):

  A
 / \
B   C
 \ /
  D

then servers will handle D as normal. D is sent to the servers' clients (assuming D passes auth checks). The state at D may resolve to a state that includes C, in which case clients should also to be told that the state has changed to include C. (Note: This depends on the exact state resolution algorithm used. In the original version of the algorithm C would be in the resolved state, whereas in latter versions the algorithm tries to prioritise the ban over the topic change.)

Note that this is essentially equivalent to the situation where one server doesn’t receive C at all, and so asks another server for the state of the C branch.

Let’s go back to the graph before D was sent:

  A
 / \
B   C

If all the servers in the room saw B before C and so soft fail C, then any new event D' will not reference C:

  A
 / \
B   C
|
D'

Retrieving event authorization information

The homeserver may be missing event authorization information, or wish to check with other servers to ensure it is receiving the correct auth chain. These APIs give the homeserver an avenue for getting the information it needs.

{
  "auth_chain": [
    {
      "content": {
        "see_room_version_spec": "The event format changes depending on the room version."
      },
      "room_id": "!somewhere:example.org",
      "type": "m.room.minimal_pdu"
    }
  ]
}

EDUs

EDUs, by comparison to PDUs, do not have an ID, a room ID, or a list of “previous” IDs. They are intended to be non-persistent data such as user presence, typing notifications, etc.

{
  "content": {
    "key": "value"
  },
  "edu_type": "m.presence"
}

Room State Resolution

The state of a room is a map of (event_type, state_key) to event_id. Each room starts with an empty state, and each state event which is accepted into the room updates the state of that room.

Where each event has a single prev_event, it is clear what the state of the room after each event should be. However, when two branches in the event graph merge, the state of those branches might differ, so a state resolution algorithm must be used to determine the resultant state.

For example, consider the following event graph (where the oldest event, E0, is at the top):

  E0
  |
  E1
 /  \
E2  E4
|    |
E3   |
 \  /
  E5

Suppose E3 and E4 are both m.room.name events which set the name of the room. What should the name of the room be at E5?

The algorithm to be used for state resolution depends on the room version. For a description of each room version’s algorithm, please see the room version specification.

Backfilling and retrieving missing events

Once a homeserver has joined a room, it receives all the events emitted by other homeservers in that room, and is thus aware of the entire history of the room from that moment onwards. Since users in that room are able to request the history by the /messages client API endpoint, it’s possible that they might step backwards far enough into history before the homeserver itself was a member of that room.

To cover this case, the federation API provides a server-to-server analog of the /messages client API, allowing one homeserver to fetch history from another. This is the /backfill API.

To request more history, the requesting homeserver picks another homeserver that it thinks may have more (most likely this should be a homeserver for some of the existing users in the room at the earliest point in history it has currently), and makes a /backfill request.

Similar to backfilling a room’s history, a server may not have all the events in the graph. That server may use the /get_missing_events API to acquire the events it is missing.

{
  "origin": "matrix.org",
  "origin_server_ts": 1234567890,
  "pdus": [
    {
      "content": {
        "see_room_version_spec": "The event format changes depending on the room version."
      },
      "room_id": "!somewhere:example.org",
      "type": "m.room.minimal_pdu"
    }
  ]
}

{
  "earliest_events": [
    "$missing_event:example.org"
  ],
  "latest_events": [
    "$event_that_has_the_missing_event_as_a_previous_event:example.org"
  ],
  "limit": 10
}

{
  "events": [
    {
      "content": {
        "see_room_version_spec": "The event format changes depending on the room version."
      },
      "room_id": "!somewhere:example.org",
      "type": "m.room.minimal_pdu"
    }
  ]
}

Retrieving events

In some circumstances, a homeserver may be missing a particular event or information about the room which cannot be easily determined from backfilling. These APIs provide homeservers with the option of getting events and the state of the room at a given point in the timeline.

{
  "origin": "matrix.org",
  "origin_server_ts": 1234567890,
  "pdus": [
    {
      "content": {
        "see_room_version_spec": "The event format changes depending on the room version."
      },
      "room_id": "!somewhere:example.org",
      "type": "m.room.minimal_pdu"
    }
  ]
}

{
  "auth_chain": [
    {
      "content": {
        "see_room_version_spec": "The event format changes depending on the room version."
      },
      "room_id": "!somewhere:example.org",
      "type": "m.room.minimal_pdu"
    }
  ],
  "pdus": [
    {
      "content": {
        "see_room_version_spec": "The event format changes depending on the room version."
      },
      "room_id": "!somewhere:example.org",
      "type": "m.room.minimal_pdu"
    }
  ]
}

{
  "auth_chain_ids": [
    "$an_event:example.org"
  ],
  "pdu_ids": [
    "$an_event:example.org"
  ]
}

{
  "event_id": "$143273582443PhrSn:example.org",
  "origin_server_ts": 1432735824653
}

{
  "errcode": "M_NOT_FOUND",
  "error": "Unable to find event from 1432684800000 in forward direction"
}

Joining Rooms

When a new user wishes to join a room that the user’s homeserver already knows about, the homeserver can immediately determine if this is allowable by inspecting the state of the room. If it is acceptable, it can generate, sign, and emit a new m.room.member state event adding the user into that room. When the homeserver does not yet know about the room it cannot do this directly. Instead, it must take a longer multi-stage handshaking process by which it first selects a remote homeserver which is already participating in that room, and use it to assist in the joining process. This is the remote join handshake.

This handshake involves the homeserver of the new member wishing to join (referred to here as the “joining” server), the directory server hosting the room alias the user is requesting to join with, and a homeserver where existing room members are already present (referred to as the “resident” server).

In summary, the remote join handshake consists of the joining server querying the directory server for information about the room alias; receiving a room ID and a list of join candidates. The joining server then requests information about the room from one of the residents. It uses this information to construct an m.room.member event which it finally sends to a resident server.

Conceptually these are three different roles of homeserver. In practice the directory server is likely to be resident in the room, and so may be selected by the joining server to be the assisting resident. Likewise, it is likely that the joining server picks the same candidate resident for both phases of event construction, though in principle any valid candidate may be used at each time. Thus, any join handshake can potentially involve anywhere from two to four homeservers, though most in practice will use just two.

+---------+          +---------------+            +-----------------+ +-----------------+
| Client  |          | JoiningServer |            | DirectoryServer | | ResidentServer  |
+---------+          +---------------+            +-----------------+ +-----------------+
     |                       |                             |                   |
     | join request          |                             |                   |
     |---------------------->|                             |                   |
     |                       |                             |                   |
     |                       | directory request           |                   |
     |                       |---------------------------->|                   |
     |                       |                             |                   |
     |                       |          directory response |                   |
     |                       |<----------------------------|                   |
     |                       |                             |                   |
     |                       | make_join request           |                   |
     |                       |------------------------------------------------>|
     |                       |                             |                   |
     |                       |                             |make_join response |
     |                       |<------------------------------------------------|
     |                       |                             |                   |
     |                       | send_join request           |                   |
     |                       |------------------------------------------------>|
     |                       |                             |                   |
     |                       |                             |send_join response |
     |                       |<------------------------------------------------|
     |                       |                             |                   |
     |         join response |                             |                   |
     |<----------------------|                             |                   |
     |                       |                             |                   |

The first part of the handshake usually involves using the directory server to request the room ID and join candidates through the /query/directory API endpoint. In the case of a new user joining a room as a result of a received invite, the joining user’s homeserver could optimise this step away by picking the origin server of that invite message as the join candidate. However, the joining server should be aware that the origin server of the invite might since have left the room, so should be prepared to fall back on the regular join flow if this optimisation fails.

Once the joining server has the room ID and the join candidates, it then needs to obtain enough information about the room to fill in the required fields of the m.room.member event. It obtains this by selecting a resident from the candidate list, and using the GET /make_join endpoint. The resident server will then reply with enough information for the joining server to fill in the event.

The joining server is expected to add or replace the origin, origin_server_ts, and event_id on the templated event received by the resident server. This event is then signed by the joining server.

To complete the join handshake, the joining server submits this new event to the resident server it used for GET /make_join, using the PUT /send_join endpoint.

The resident homeserver then adds its signature to this event and accepts it into the room’s event graph. The joining server receives the full set of state for the newly-joined room as well as the freshly signed membership event. The resident server must also send the event to other servers participating in the room.

{
  "event": {
    "content": {
      "join_authorised_via_users_server": "@anyone:resident.example.org",
      "membership": "join"
    },
    "origin": "example.org",
    "origin_server_ts": 1549041175876,
    "room_id": "!somewhere:example.org",
    "sender": "@someone:example.org",
    "state_key": "@someone:example.org",
    "type": "m.room.member"
  },
  "room_version": "2"
}

{
  "errcode": "M_INCOMPATIBLE_ROOM_VERSION",
  "error": "Your homeserver does not support the features required to join this room",
  "room_version": "3"
}

{
  "errcode": "M_FORBIDDEN",
  "error": "You are not invited to this room"
}

{
  "errcode": "M_NOT_FOUND",
  "error": "Unknown room"
}

{
  "content": {
    "membership": "join"
  },
  "origin": "matrix.org",
  "origin_server_ts": 1234567890,
  "sender": "@someone:example.org",
  "state_key": "@someone:example.org",
  "type": "m.room.member"
}

[
  200,
  {
    "auth_chain": [
      {
        "content": {
          "see_room_version_spec": "The event format changes depending on the room version."
        },
        "room_id": "!somewhere:example.org",
        "type": "m.room.minimal_pdu"
      }
    ],
    "event": {
      "auth_events": [
        "$urlsafe_base64_encoded_eventid",
        "$a-different-event-id"
      ],
      "content": {
        "join_authorised_via_users_server": "@arbitrary:resident.example.com",
        "membership": "join"
      },
      "depth": 12,
      "hashes": {
        "sha256": "thishashcoversallfieldsincasethisisredacted"
      },
      "origin": "example.com",
      "origin_server_ts": 1404838188000,
      "prev_events": [
        "$urlsafe_base64_encoded_eventid",
        "$a-different-event-id"
      ],
      "room_id": "!UcYsUzyxTGDxLBEvLy:example.org",
      "sender": "@alice:example.com",
      "signatures": {
        "example.com": {
          "ed25519:key_version": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
        },
        "resident.example.com": {
          "ed25519:other_key_version": "a different signature"
        }
      },
      "state_key": "@alice:example.com",
      "type": "m.room.member",
      "unsigned": {
        "age": 4612
      }
    },
    "origin": "matrix.org",
    "state": [
      {
        "content": {
          "see_room_version_spec": "The event format changes depending on the room version."
        },
        "room_id": "!somewhere:example.org",
        "type": "m.room.minimal_pdu"
      }
    ]
  }
]

{
  "content": {
    "membership": "join"
  },
  "origin": "matrix.org",
  "origin_server_ts": 1234567890,
  "sender": "@someone:example.org",
  "state_key": "@someone:example.org",
  "type": "m.room.member"
}

{
  "auth_chain": [
    {
      "content": {
        "see_room_version_spec": "The event format changes depending on the room version."
      },
      "room_id": "!somewhere:example.org",
      "type": "m.room.minimal_pdu"
    }
  ],
  "event": {
    "auth_events": [
      "$urlsafe_base64_encoded_eventid",
      "$a-different-event-id"
    ],
    "content": {
      "join_authorised_via_users_server": "@arbitrary:resident.example.com",
      "membership": "join"
    },
    "depth": 12,
    "hashes": {
      "sha256": "thishashcoversallfieldsincasethisisredacted"
    },
    "origin": "example.com",
    "origin_server_ts": 1404838188000,
    "prev_events": [
      "$urlsafe_base64_encoded_eventid",
      "$a-different-event-id"
    ],
    "room_id": "!UcYsUzyxTGDxLBEvLy:example.org",
    "sender": "@alice:example.com",
    "signatures": {
      "example.com": {
        "ed25519:key_version": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
      },
      "resident.example.com": {
        "ed25519:other_key_version": "a different signature"
      }
    },
    "state_key": "@alice:example.com",
    "type": "m.room.member",
    "unsigned": {
      "age": 4612
    }
  },
  "members_omitted": true,
  "origin": "matrix.org",
  "servers_in_room": [
    "matrix.org",
    "example.com"
  ],
  "state": [
    {
      "content": {
        "see_room_version_spec": "The event format changes depending on the room version."
      },
      "room_id": "!somewhere:example.org",
      "type": "m.room.minimal_pdu"
    }
  ]
}

{
  "errcode": "M_UNABLE_TO_GRANT_JOIN",
  "error": "This server cannot send invites to you."
}

{
  "errcode": "M_FORBIDDEN",
  "error": "You are not invited to this room"
}

Restricted rooms

Restricted rooms are described in detail in the client-server API and are available in room versions which support restricted join rules.

A resident server processing a request to join a restricted room must ensure that the joining server satisfies at least one of the conditions specified by m.room.join_rules. If no conditions are available, or none match the required schema, then the joining server is considered to have failed all conditions.

The resident server uses a 400 M_UNABLE_TO_AUTHORISE_JOIN error on /make_join and /send_join to denote that the resident server is unable to validate any of the conditions, usually because the resident server does not have state information about rooms required by the conditions.

The resident server uses a 400 M_UNABLE_TO_GRANT_JOIN error on /make_join and /send_join to denote that the joining server should try a different server. This is typically because the resident server can see that the joining user satisfies one of the conditions, though the resident server would be unable to meet the auth rules governing join_authorised_via_users_server on the resulting m.room.member event.

If the joining server fails all conditions then a 403 M_FORBIDDEN error is used by the resident server.

Rooms can permit knocking through the join rules, and if permitted this gives users a way to request to join (be invited) to the room. Users who knock on a room where the server is already a resident of the room can just send the knock event directly without using this process, however much like joining rooms the server must handshake their way into having the knock sent on its behalf.

The handshake is largely the same as the joining rooms handshake, where instead of a “joining server” there is a “knocking server”, and the APIs to be called are different (/make_knock and /send_knock).

Servers can retract knocks over federation by leaving the room, as described below for rejecting invites.

{
  "event": {
    "content": {
      "membership": "knock"
    },
    "origin": "example.org",
    "origin_server_ts": 1549041175876,
    "room_id": "!somewhere:example.org",
    "sender": "@someone:example.org",
    "state_key": "@someone:example.org",
    "type": "m.room.member"
  },
  "room_version": "7"
}

{
  "errcode": "M_INCOMPATIBLE_ROOM_VERSION",
  "error": "Your homeserver does not support the features required to knock on this room",
  "room_version": "7"
}

{
  "errcode": "M_FORBIDDEN",
  "error": "You are not permitted to knock on this room"
}

{
  "errcode": "M_NOT_FOUND",
  "error": "Unknown room"
}

{
  "content": {
    "membership": "knock"
  },
  "origin": "matrix.org",
  "origin_server_ts": 1234567890,
  "sender": "@someone:example.org",
  "state_key": "@someone:example.org",
  "type": "m.room.member"
}

{
  "knock_room_state": [
    {
      "content": {
        "name": "Example Room"
      },
      "sender": "@bob:example.org",
      "state_key": "",
      "type": "m.room.name"
    },
    {
      "content": {
        "join_rule": "knock"
      },
      "sender": "@bob:example.org",
      "state_key": "",
      "type": "m.room.join_rules"
    }
  ]
}

{
  "errcode": "M_FORBIDDEN",
  "error": "You are not permitted to knock on this room"
}

{
  "errcode": "M_NOT_FOUND",
  "error": "Unknown room"
}

Inviting to a room

When a user on a given homeserver invites another user on the same homeserver, the homeserver may sign the membership event itself and skip the process defined here. However, when a user invites another user on a different homeserver, a request to that homeserver to have the event signed and verified must be made.

Note that invites are used to indicate that knocks were accepted. As such, receiving servers should be prepared to manually link up a previous knock to an invite if the invite event does not directly reference the knock.

{
  "content": {
    "membership": "invite"
  },
  "origin": "matrix.org",
  "origin_server_ts": 1234567890,
  "sender": "@someone:example.org",
  "state_key": "@joe:elsewhere.com",
  "type": "m.room.member",
  "unsigned": {
    "invite_room_state": [
      {
        "content": {
          "name": "Example Room"
        },
        "sender": "@bob:example.org",
        "state_key": "",
        "type": "m.room.name"
      },
      {
        "content": {
          "join_rule": "invite"
        },
        "sender": "@bob:example.org",
        "state_key": "",
        "type": "m.room.join_rules"
      }
    ]
  }
}

[
  200,
  {
    "event": {
      "content": {
        "membership": "invite"
      },
      "origin": "example.org",
      "origin_server_ts": 1549041175876,
      "room_id": "!somewhere:example.org",
      "sender": "@someone:example.org",
      "signatures": {
        "elsewhere.com": {
          "ed25519:k3y_versi0n": "SomeOtherSignatureHere"
        },
        "example.com": {
          "ed25519:key_version": "SomeSignatureHere"
        }
      },
      "state_key": "@someone:example.org",
      "type": "m.room.member",
      "unsigned": {
        "invite_room_state": [
          {
            "content": {
              "name": "Example Room"
            },
            "sender": "@bob:example.org",
            "state_key": "",
            "type": "m.room.name"
          },
          {
            "content": {
              "join_rule": "invite"
            },
            "sender": "@bob:example.org",
            "state_key": "",
            "type": "m.room.join_rules"
          }
        ]
      }
    }
  }
]

{
  "errcode": "M_FORBIDDEN",
  "error": "User cannot invite the target user."
}

{
  "event": {
    "content": {
      "membership": "invite"
    },
    "origin": "matrix.org",
    "origin_server_ts": 1234567890,
    "sender": "@someone:example.org",
    "state_key": "@joe:elsewhere.com",
    "type": "m.room.member"
  },
  "invite_room_state": [
    {
      "content": {
        "name": "Example Room"
      },
      "sender": "@bob:example.org",
      "state_key": "",
      "type": "m.room.name"
    },
    {
      "content": {
        "join_rule": "invite"
      },
      "sender": "@bob:example.org",
      "state_key": "",
      "type": "m.room.join_rules"
    }
  ],
  "room_version": "2"
}

{
  "event": {
    "content": {
      "membership": "invite"
    },
    "origin": "example.org",
    "origin_server_ts": 1549041175876,
    "room_id": "!somewhere:example.org",
    "sender": "@someone:example.org",
    "signatures": {
      "elsewhere.com": {
        "ed25519:k3y_versi0n": "SomeOtherSignatureHere"
      },
      "example.com": {
        "ed25519:key_version": "SomeSignatureHere"
      }
    },
    "state_key": "@someone:example.org",
    "type": "m.room.member",
    "unsigned": {
      "invite_room_state": [
        {
          "content": {
            "name": "Example Room"
          },
          "sender": "@bob:example.org",
          "state_key": "",
          "type": "m.room.name"
        },
        {
          "content": {
            "join_rule": "invite"
          },
          "sender": "@bob:example.org",
          "state_key": "",
          "type": "m.room.join_rules"
        }
      ]
    }
  }
}

{
  "errcode": "M_INCOMPATIBLE_ROOM_VERSION",
  "error": "Your homeserver does not support the features required to join this room",
  "room_version": "3"
}

{
  "errcode": "M_FORBIDDEN",
  "error": "User cannot invite the target user."
}

Leaving Rooms (Rejecting Invites)

Normally homeservers can send appropriate m.room.member events to have users leave the room, to reject local invites, or to retract a knock. Remote invites/knocks from other homeservers do not involve the server in the graph and therefore need another approach to reject the invite. Joining the room and promptly leaving is not recommended as clients and servers will interpret that as accepting the invite, then leaving the room rather than rejecting the invite.

Similar to the Joining Rooms handshake, the server which wishes to leave the room starts with sending a /make_leave request to a resident server. In the case of rejecting invites, the resident server may be the server which sent the invite. After receiving a template event from /make_leave, the leaving server signs the event and replaces the event_id with its own. This is then sent to the resident server via /send_leave. The resident server will then send the event to other servers in the room.

{
  "event": {
    "content": {
      "membership": "leave"
    },
    "origin": "example.org",
    "origin_server_ts": 1549041175876,
    "room_id": "!somewhere:example.org",
    "sender": "@someone:example.org",
    "state_key": "@someone:example.org",
    "type": "m.room.member"
  },
  "room_version": "2"
}

{
  "errcode": "M_FORBIDDEN",
  "error": "User is not in the room."
}

{
  "content": {
    "membership": "leave"
  },
  "depth": 12,
  "origin": "matrix.org",
  "origin_server_ts": 1234567890,
  "sender": "@someone:example.org",
  "state_key": "@someone:example.org",
  "type": "m.room.member"
}

[
  200,
  {}
]

{
  "content": {
    "membership": "leave"
  },
  "depth": 12,
  "origin": "matrix.org",
  "origin_server_ts": 1234567890,
  "sender": "@someone:example.org",
  "state_key": "@someone:example.org",
  "type": "m.room.member"
}

{}

Third-party invites

When a user wants to invite another user in a room but doesn’t know the Matrix ID to invite, they can do so using a third-party identifier (e.g. an e-mail or a phone number).

This identifier and its bindings to Matrix IDs are verified by an identity server implementing the Identity Service API.

Cases where an association exists for a third-party identifier

If the third-party identifier is already bound to a Matrix ID, a lookup request on the identity server will return it. The invite is then processed by the inviting homeserver as a standard m.room.member invite event. This is the simplest case.

Cases where an association doesn’t exist for a third-party identifier

If the third-party identifier isn’t bound to any Matrix ID, the inviting homeserver will request the identity server to store an invite for this identifier and to deliver it to whoever binds it to its Matrix ID. It will also send an m.room.third_party_invite event in the room to specify a display name, a token and public keys the identity server provided as a response to the invite storage request.

When a third-party identifier with pending invites gets bound to a Matrix ID, the identity server will send a POST request to the ID’s homeserver as described in the Invitation Storage section of the Identity Service API.

The following process applies for each invite sent by the identity server:

The invited homeserver will create an m.room.member invite event containing a special third_party_invite section containing the token and a signed object, both provided by the identity server.

If the invited homeserver is in the room the invite came from, it can auth the event and send it.

However, if the invited homeserver isn’t in the room the invite came from, it will need to request the room’s homeserver to auth the event.

{
  "address": "[email protected]",
  "invites": [
    {
      "address": "[email protected]",
      "medium": "email",
      "mxid": "@alice:matrix.org",
      "room_id": "!somewhere:example.org",
      "sender": "@bob:matrix.org",
      "signed": {
        "mxid": "@alice:matrix.org",
        "signatures": {
          "vector.im": {
            "ed25519:0": "SomeSignatureGoesHere"
          }
        },
        "token": "Hello World"
      }
    }
  ],
  "medium": "email",
  "mxid": "@alice:matrix.org"
}

{}

{
  "content": {
    "membership": "invite",
    "third_party_invite": {
      "display_name": "alice",
      "signed": {
        "mxid": "@alice:localhost",
        "signatures": {
          "magic.forest": {
            "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
          }
        },
        "token": "abc123"
      }
    }
  },
  "room_id": "!abc123:matrix.org",
  "sender": "@joe:matrix.org",
  "state_key": "@someone:example.org",
  "type": "m.room.member"
}