1.1   Other versions of this specification

The following other versions are also available, in reverse chronological order:

• HEAD: Includes all changes since the latest versioned release.
• r0.1.0

2.1   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 IP address using 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 an AAAA or A record 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 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 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>.

The TLS certificate provided by the target server must be signed by a known Certificate Authority. 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.

GET /.well-known/matrix/server HTTP/1.1

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

2.2   Server implementation

GET /_matrix/federation/v1/version HTTP/1.1

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

2.3   Retrieving server keys

Each homeserver publishes its public keys under /_matrix/key/v2/server/{keyId}. Homeservers query for keys by either getting /_matrix/key/v2/server/{keyId} directly or by querying an intermediate notary server using a /_matrix/key/v2/query/{serverName}/{keyId} API. Intermediate notary servers query the /_matrix/key/v2/server/{keyId} 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.

GET /_matrix/key/v2/server/ed25519%3Aabc123 HTTP/1.1

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

GET /_matrix/key/v2/query/matrix.org/ed25519%3Aabc123?minimum_valid_until_ts=1234567890 HTTP/1.1

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

POST /_matrix/key/v2/query HTTP/1.1
Content-Type: application/json

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

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

3.1   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": <request body>,
     "signatures": {
         "origin.hs.example.com": {
             "ed25519:key1": "ABCDEF..."
         }
     }
}

Step 2 add Authorization header:

GET /target HTTP/1.1
Authorization: X-Matrix origin=origin.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_json is not None:
        request["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,key=\"%s\",sig=\"%s\"" % (
                origin_name, key, sig,
            )
        ))

    return ("Authorization", authorization_headers)

3.2   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.

3.3   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.

4.1   PUT /_matrix/federation/v1/send/{txnId}

Push messages representing live activity to another server. The destination name will be set to that of the receiving server itself. Each embedded PDU in the transaction body will be processed.

The sending server must wait and retry for a 200 OK response before sending a transaction with a different txnId to the receiving server.

Note that events have a different format depending on the room version - check the room version specification for precise event formats.

Request format:

Response format:

Example request:

PUT /_matrix/federation/v1/send/S0meTransacti0nId HTTP/1.1
Content-Type: application/json

{
  "origin": "example.org",
  "origin_server_ts": 1532991320875,
  "pdus": [
    {
      "type": "m.room.minimal_pdu",
      "room_id": "!somewhere:example.org",
      "content": {
        "see_room_version_spec": "The event format changes depending on the room version."
      }
    }
  ],
  "edus": [
    {
      "edu_type": "m.presence",
      "content": {
        "key": "value"
      }
    }
  ]
}

Response:

Status code 200:

The result of processing the transaction. The server is to use this response even in the event of one or more PDUs failing to be processed.

Example

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

5.1   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.
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 at 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.

  A
 /
B

  A
 / \
B   C

  A
 / \
B   C
 \ /
  D

  A
 / \
B   C

  A
 / \
B   C
|
D

GET /_matrix/federation/v1/event_auth/%21abc123%3Amatrix.org/%24helloworld%3Aexample.org HTTP/1.1

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

POST /_matrix/federation/v1/query_auth/%21abc123%3Amatrix.org/%24helloworld%3Aexample.org HTTP/1.1
Content-Type: application/json

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

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

6.1   Ephemeral Data Unit schema

An ephemeral data unit.

Ephemeral Data Unit

Example:

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

8.1   GET /_matrix/federation/v1/backfill/{roomId}

Retrieves a sliding-window history of previous PDUs that occurred in the given room. Starting from the PDU ID(s) given in the v argument, the PDUs that preceded it are retrieved, up to the total number given by the limit.

Request format:

Response format:

Example request:

GET /_matrix/federation/v1/backfill/%21SomeRoom%3Amatrix.org?v=%24abc123%3Amatrix.org&limit=2 HTTP/1.1

Response:

Status code 200:

A transaction containing the PDUs that preceded the given event(s), including the given event(s), up to the given limit.

Example

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

8.2   POST /_matrix/federation/v1/get_missing_events/{roomId}

Retrieves previous events that the sender is missing. This is done by doing a breadth-first walk of the prev_events for the latest_events, ignoring any events in earliest_events and stopping at the limit.

Request format:

Response format:

Example request:

POST /_matrix/federation/v1/get_missing_events/%21SomeRoom%3Amatrix.org HTTP/1.1
Content-Type: application/json

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

Response:

Status code 200:

The previous events for latest_events, excluding any earliest_events, up to the provided limit.

Example

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

9.1   GET /_matrix/federation/v1/state/{roomId}

Retrieves a snapshot of a room's state at a given event.

Request format:

Response format:

Example request:

GET /_matrix/federation/v1/state/%21abc123%3Amatrix.org?event_id=%24helloworld%3Amatrix.org HTTP/1.1

Response:

Status code 200:

The fully resolved state for the room, prior to considering any state changes induced by the requested event. Includes the authorization chain for the events.

Example

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

9.2   GET /_matrix/federation/v1/state_ids/{roomId}

Retrieves a snapshot of a room's state at a given event, in the form of event IDs. This performs the same function as calling /state/{roomId}, however this returns just the event IDs rather than the full events.

Request format:

Response format:

Example request:

GET /_matrix/federation/v1/state_ids/%21abc123%3Amatrix.org?event_id=%24helloworld%3Amatrix.org HTTP/1.1

Response:

Status code 200:

The fully resolved state for the room, prior to considering any state changes induced by the requested event. Includes the authorization chain for the events.

Example

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

9.3   GET /_matrix/federation/v1/event/{eventId}

Retrieves a single event.

Request format:

Response format:

Example request:

GET /_matrix/federation/v1/event/%24abc123%3Amatrix.org HTTP/1.1

Response:

Status code 200:

A transaction containing a single PDU which is the event requested.

Example

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

10.1   GET /_matrix/federation/v1/make_join/{roomId}/{userId}

Asks the receiving server to return information that the sending server will need to prepare a join event to get into the room.

Request format:

Response format:

Example request:

GET /_matrix/federation/v1/make_join/%21abc123%3Amatrix.org/%40someone%3Aexample.org?ver=1&ver=2 HTTP/1.1

Responses:

Status code 200:

A template to be used for the rest of the Joining Rooms handshake. Note that events have a different format depending on the room version - check the room version specification for precise event formats. The response body here describes the common event fields in more detail and may be missing other required fields for a PDU.

Example

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

Status code 400:

The request is invalid or the room the server is attempting to join has a version that is not listed in the ver parameters.

The error should be passed through to clients so that they may give better feedback to users.

Example

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

10.2   PUT /_matrix/federation/v1/send_join/{roomId}/{eventId}

Submits a signed join event to the resident server for it to accept it into the room's graph. Note that events have a different format depending on the room version - check the room version specification for precise event formats. The request and response body here describes the common event fields in more detail and may be missing other required fields for a PDU.

Request format:

Response format:

Example request:

PUT /_matrix/federation/v1/send_join/%21abc123%3Amatrix.org/%24abc123%3Aexample.org HTTP/1.1
Content-Type: application/json

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

Response:

Status code 200:

The full state for the room, having accepted the join event.

Example

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

11.1   PUT /_matrix/federation/v1/invite/{roomId}/{eventId}

Invites a remote user to a room. Once the event has been signed by both the inviting homeserver and the invited homeserver, it can be sent to all of the servers in the room by the inviting homeserver.

Servers should prefer to use the v2 API for invites instead of the v1 API. Servers which receive a v1 invite request must assume that the room version is either "1" or "2".

Note that events have a different format depending on the room version - check the room version specification for precise event formats. The request and response bodies here describe the common event fields in more detail and may be missing other required fields for a PDU.

Request format:

Response format:

Example request:

PUT /_matrix/federation/v1/invite/%21abc123%3Amatrix.org/%24abc123%3Aexample.org HTTP/1.1
Content-Type: application/json

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

Responses:

Status code 200:

The event with the invited server's signature added. All other fields of the events should remain untouched. Note that events have a different format depending on the room version - check the room version specification for precise event formats.

Example

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

Status code 403:

The invite is not allowed. This could be for a number of reasons, including:

• The sender is not allowed to send invites to the target user/homeserver.
• The homeserver does not permit anyone to invite its users.
• The homeserver refuses to participate in the room.

Example

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

11.2   PUT /_matrix/federation/v2/invite/{roomId}/{eventId}

Invites a remote user to a room. Once the event has been signed by both the inviting homeserver and the invited homeserver, it can be sent to all of the servers in the room by the inviting homeserver.

This endpoint is preferred over the v1 API as it is more useful for servers. Senders which receive a 400 or 404 response to this endpoint should retry using the v1 API as the server may be older, if the room version is "1" or "2".

Note that events have a different format depending on the room version - check the room version specification for precise event formats. The request and response bodies here describe the common event fields in more detail and may be missing other required fields for a PDU.

Request format:

Response format:

Example request:

PUT /_matrix/federation/v2/invite/%21abc123%3Amatrix.org/%24abc123%3Aexample.org HTTP/1.1
Content-Type: application/json

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

Responses:

Status code 200:

The event with the invited server's signature added. All other fields of the events should remain untouched. Note that events have a different format depending on the room version - check the room version specification for precise event formats.

Example

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

Status code 400:

The request is invalid or the room the server is attempting to join has a version that is not listed in the ver parameters.

The error should be passed through to clients so that they may give better feedback to users.

Example

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

Status code 403:

The invite is not allowed. This could be for a number of reasons, including:

• The sender is not allowed to send invites to the target user/homeserver.
• The homeserver does not permit anyone to invite its users.
• The homeserver refuses to participate in the room.

Example

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

12.1   GET /_matrix/federation/v1/make_leave/{roomId}/{userId}

Asks the receiving server to return information that the sending server will need to prepare a leave event to get out of the room.

Request format:

Response format:

Example request:

GET /_matrix/federation/v1/make_leave/%21abc123%3Amatrix.org/%40someone%3Aexample.org HTTP/1.1

Responses:

Status code 200:

A template to be used to call /send_leave. Note that events have a different format depending on the room version - check the room version specification for precise event formats. The response body here describes the common event fields in more detail and may be missing other required fields for a PDU.

Example

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

Status code 403:

The request is not authorized. This could mean that the user is not in the room.

Example

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

12.2   PUT /_matrix/federation/v1/send_leave/{roomId}/{eventId}

Submits a signed leave event to the resident server for it to accept it into the room's graph. Note that events have a different format depending on the room version - check the room version specification for precise event formats. The request and response body here describes the common event fields in more detail and may be missing other required fields for a PDU.

Request format:

Response format:

Example request:

PUT /_matrix/federation/v1/send_leave/%21abc123%3Amatrix.org/%24abc123%3Aexample.org HTTP/1.1
Content-Type: application/json

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

Response:

Status code 200:

An empty response to indicate the event was accepted into the graph by the receiving homeserver.

Example

[
  200,
  {}
]

13.1   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.

13.2   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 a 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 a 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.

PUT /_matrix/federation/v1/exchange_third_party_invite/%21abc123%3Amatrix.org HTTP/1.1
Content-Type: application/json

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

{}

PUT /_matrix/federation/v1/3pid/onbind HTTP/1.1
Content-Type: application/json

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

{}

14.1   GET /_matrix/federation/v1/publicRooms

Gets all the public rooms for the homeserver. This should not return rooms that are listed on another homeserver's directory, just those listed on the receiving homeserver's directory.

Request format:

Response format:

Example request:

GET /_matrix/federation/v1/publicRooms?limit=10&since=GetMoreRoomsTokenHere&include_all_networks=False&third_party_instance_id=irc HTTP/1.1

Response:

Status code 200:

The public room list for the homeserver.

Example

{
  "chunk": [
    {
      "aliases": [
        "#murrays:cheese.bar"
      ],
      "avatar_url": "mxc://bleeker.street/CHEDDARandBRIE",
      "guest_can_join": false,
      "name": "CHEESE",
      "num_joined_members": 37,
      "room_id": "!ol19s:bleecker.street",
      "topic": "Tasty tasty cheese",
      "world_readable": true
    }
  ],
  "next_batch": "p190q",
  "prev_batch": "p1902",
  "total_room_count_estimate": 115
}

15.1   m.typing schema

A typing notification EDU for a user in a room.

m.typing

Typing Notification

Example:

{
    "content": {
        "room_id": "!somewhere:matrix.org",
        "typing": true,
        "user_id": "@john:matrix.org"
    },
    "edu_type": "m.typing"
}

16.1   m.presence schema

An EDU representing presence updates for users of the sending homeserver.

m.presence

Presence Update

User Presence Update

Example:

{
    "content": {
        "push": [
            {
                "currently_active": true,
                "last_active_ago": 5000,
                "presence": "online",
                "status_msg": "Making cupcakes",
                "user_id": "@john:matrix.org"
            }
        ]
    },
    "edu_type": "m.presence"
}

17.1   m.receipt schema

An EDU representing receipt updates for users of the sending homeserver. When receiving receipts, the server should only update entries that are listed in the EDU. Receipts previously received that do not appear in the EDU should not be removed or otherwise manipulated.

m.receipt

Room Receipts

User Read Receipt

Read Receipt Metadata

Example:

{
    "content": {
        "!some_room:example.org": {
            "m.read": {
                "@john:matrix.org": {
                    "data": {
                        "ts": 1533358089009
                    },
                    "event_ids": [
                        "$read_this_event:matrix.org"
                    ]
                }
            }
        }
    },
    "edu_type": "m.receipt"
}

18.1   GET /_matrix/federation/v1/query/{queryType}

Performs a single query request on the receiving homeserver. The query string arguments are dependent on which type of query is being made. Known query types are specified as their own endpoints as an extension to this definition.

Request format:

Example request:

GET /_matrix/federation/v1/query/profile HTTP/1.1

Response:

Status code 200:

The query response. The schema varies depending on the query being made.

18.2   GET /_matrix/federation/v1/query/directory

Performs a query to get the mapped room ID and list of resident homeservers in the room for a given room alias. Homeservers should only query room aliases that belong to the target server (identified by the DNS Name in the alias).

Servers may wish to cache the response to this query to avoid requesting the information too often.

Request format:

Response format:

Example request:

GET /_matrix/federation/v1/query/directory?room_alias=%23room_alias%3Aexample.org HTTP/1.1

Responses:

Status code 200:

The corresponding room ID and list of known resident homeservers for the room.

Example

{
  "room_id": "!roomid1234:example.org",
  "servers": [
    "example.org",
    "example.com",
    "another.example.com:8449"
  ]
}

Status code 404:

The room alias was not found.

Example

{
  "errcode": "M_NOT_FOUND",
  "error": "Room alias not found."
}

18.3   GET /_matrix/federation/v1/query/profile

Performs a query to get profile information, such as a display name or avatar, for a given user. Homeservers should only query profiles for users that belong to the target server (identified by the DNS Name in the user ID).

Servers may wish to cache the response to this query to avoid requesting the information too often.

Request format:

Response format:

Example request:

GET /_matrix/federation/v1/query/profile?user_id=%40someone%3Aexample.org HTTP/1.1

Responses:

Status code 200:

The profile for the user. If a field is specified in the request, only the matching field should be included in the response. If no field was specified, the response should include the fields of the user's profile that can be made public, such as the display name and avatar.

If the user does not have a particular field set on their profile, the server should exclude it from the response body or give it the value null.

Example

{
  "displayname": "John Doe",
  "avatar_url": "mxc://matrix.org/MyC00lAvatar"
}

Status code 404:

The user does not exist or does not have a profile.

Example

{
  "errcode": "M_NOT_FOUND",
  "error": "User does not exist."
}

19.1   GET /_matrix/federation/v1/openid/userinfo

Exchanges an OpenID access token for information about the user who generated the token. Currently this only exposes the Matrix User ID of the owner.

Request format:

Response format:

Example request:

GET /_matrix/federation/v1/openid/userinfo HTTP/1.1

Responses:

Status code 200:

Information about the user who generated the OpenID access token.

Example

{
  "sub": "@alice:example.com"
}

Status code 401:

The token was not recognized or has expired.

Example

{
  "errcode": "M_UNKNOWN_TOKEN",
  "error": "Access token unknown or expired"
}

20.1   GET /_matrix/federation/v1/user/devices/{userId}

Gets information on all of the user's devices

Request format:

Response format:

Example request:

GET /_matrix/federation/v1/user/devices/%40alice%3Aexample.org HTTP/1.1

Response:

Status code 200:

The user's devices.

Example

{
  "user_id": "@alice:example.org",
  "stream_id": 5,
  "devices": [
    {
      "device_id": "JLAFKJWSCS",
      "keys": {
        "user_id": "@alice:example.com",
        "device_id": "JLAFKJWSCS",
        "algorithms": [
          "m.olm.curve25519-aes-sha256",
          "m.megolm.v1.aes-sha"
        ],
        "keys": {
          "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI",
          "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
        },
        "signatures": {
          "@alice:example.com": {
            "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA"
          }
        }
      },
      "device_display_name": "Alice's Mobile Phone"
    }
  ]
}

20.2   m.device_list_update schema

An EDU that lets servers push details to each other when one of their users adds a new device to their account, required for E2E encryption to correctly target the current set of devices for a given user.

m.device_list_update

Device List Update

DeviceKeys

Example:

{
    "content": {
        "deleted": false,
        "device_display_name": "Mobile",
        "device_id": "QBUAZIFURK",
        "keys": {
            "algorithms": [
                "m.olm.curve25519-aes-sha256",
                "m.megolm.v1.aes-sha"
            ],
            "device_id": "JLAFKJWSCS",
            "keys": {
                "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI",
                "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
            },
            "signatures": {
                "@alice:example.com": {
                    "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA"
                }
            },
            "user_id": "@alice:example.com"
        },
        "prev_id": [
            5
        ],
        "stream_id": 6,
        "user_id": "@john:example.com"
    },
    "edu_type": "m.device_list_update"
}

21.1   POST /_matrix/federation/v1/user/keys/claim

Claims one-time keys for use in pre-key messages.

Request format:

Response format:

Example request:

POST /_matrix/federation/v1/user/keys/claim HTTP/1.1
Content-Type: application/json

{
  "one_time_keys": {
    "@alice:example.com": {
      "JLAFKJWSCS": "signed_curve25519"
    }
  }
}

Response:

Status code 200:

The claimed keys

Example

{
  "one_time_keys": {
    "@alice:example.com": {
      "JLAFKJWSCS": {
        "signed_curve25518:AAAAHg": {
          "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
          "signatures": {
            "@alice:example.com": {
              "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
            }
          }
        }
      }
    }
  }
}

21.2   POST /_matrix/federation/v1/user/keys/query

Returns the current devices and identity keys for the given users.

Request format:

Response format:

Example request:

POST /_matrix/federation/v1/user/keys/query HTTP/1.1
Content-Type: application/json

{
  "device_keys": {
    "@alice:example.com": []
  }
}

Response:

Status code 200:

The device information.

Example

{
  "device_keys": {
    "@alice:example.com": {
      "JLAFKJWSCS": {
        "user_id": "@alice:example.com",
        "device_id": "JLAFKJWSCS",
        "algorithms": [
          "m.olm.v1.curve25519-aes-sha256",
          "m.megolm.v1.aes-sha"
        ],
        "keys": {
          "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI",
          "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
        },
        "signatures": {
          "@alice:example.com": {
            "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA"
          }
        },
        "unsigned": {
          "device_display_name": "Alice's mobile phone"
        }
      }
    }
  }
}

22.1   m.direct_to_device schema

An EDU that lets servers push send events directly to a specific device on a remote server - for instance, to maintain an Olm E2E encrypted message channel between a local and remote device.

m.direct_to_device

To Device Message

Example:

{
    "content": {
        "message_id": "hiezohf6Hoo7kaev",
        "messages": {
            "alice@example.org": {
                "IWHQUZUIAH": {
                    "algorithm": "m.megolm.v1.aes-sha2",
                    "room_id": "!Cuyf34gef24t:localhost",
                    "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ",
                    "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8LlfJL7qNBEY..."
                }
            }
        },
        "sender": "john@example.com",
        "type": "m.room_key_request"
    },
    "edu_type": "m.direct_to_device"
}

25.1   Adding hashes and signatures to outgoing events

Before signing the event, the content hash of the event is calculated as described below. The hash is encoded using Unpadded Base64 and stored in the event object, in a hashes object, under a sha256 key.

The event object is then redacted, following the redaction algorithm. Finally it is signed as described in Signing JSON, using the server's signing key (see also Retrieving server keys).

The signature is then copied back to the original event object.

See Persistent Data Unit schema for an example of a signed event.

25.2   Validating hashes and signatures on received events

When a server receives an event over federation from another server, the receiving server should check the hashes and signatures on that event.

First the signature is checked. The event is redacted following the redaction algorithm, and the resultant object is checked for a signature from the originating server, following the algorithm described in Checking for a signature. Note that this step should succeed whether we have been sent the full event or a redacted copy.

If the signature is found to be valid, the expected content hash is calculated as described below. The content hash in the hashes property of the received event is base64-decoded, and the two are compared for equality.

If the hash check fails, then it is assumed that this is because we have only been given a redacted version of the event. To enforce this, the receiving server should use the redacted copy it calculated rather than the full copy it received.

25.3   Calculating the reference hash for an event

The reference hash of an event covers the essential fields of an event, including content hashes. It is calculated as follows.

1. The event is put through the redaction algorithm.
2. The signatures, age_ts, and unsigned properties are removed from the event, if present.
3. The event is converted into Canonical JSON.
4. A sha256 hash is calculated on the resulting JSON object.

25.4   Calculating the content hash for an event

The content hash of an event covers the complete event including the unredacted contents. It is calculated as follows.

First, any existing unsigned, signature, and hashes members are removed. The resulting object is then encoded as Canonical JSON, and the JSON is hashed using SHA-256.

25.5   Example code

def hash_and_sign_event(event_object, signing_key, signing_name):
    # First we need to hash the event object.
    content_hash = compute_content_hash(event_object)
    event_object["hashes"] = {"sha256": encode_unpadded_base64(content_hash)}

    # Strip all the keys that would be removed if the event was redacted.
    # The hashes are not stripped and cover all the keys in the event.
    # This means that we can tell if any of the non-essential keys are
    # modified or removed.
    stripped_object = strip_non_essential_keys(event_object)

    # Sign the stripped JSON object. The signature only covers the
    # essential keys and the hashes. This means that we can check the
    # signature even if the event is redacted.
    signed_object = sign_json(stripped_object, signing_key, signing_name)

    # Copy the signatures from the stripped event to the original event.
    event_object["signatures"] = signed_object["signatures"]

def compute_content_hash(event_object):
    # take a copy of the event before we remove any keys.
    event_object = dict(event_object)

    # Keys under "unsigned" can be modified by other servers.
    # They are useful for conveying information like the age of an
    # event that will change in transit.
    # Since they can be modified we need to exclude them from the hash.
    event_object.pop("unsigned", None)

    # Signatures will depend on the current value of the "hashes" key.
    # We cannot add new hashes without invalidating existing signatures.
    event_object.pop("signatures", None)

    # The "hashes" key might contain multiple algorithms if we decide to
    # migrate away from SHA-2. We don't want to include an existing hash
    # output in our hash so we exclude the "hashes" dict from the hash.
    event_object.pop("hashes", None)

    # Encode the JSON using a canonical encoding so that we get the same
    # bytes on every server for the same JSON object.
    event_json_bytes = encode_canonical_json(event_object)

    return hashlib.sha256(event_json_bytes)