matrix-spec

You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

102 KiB

Raw Blame History

title	weight	type
Client-Server API	10	docs

The client-server API allows clients to send messages, control rooms and synchronise conversation history. It is designed to support both lightweight clients which store no state and lazy-load data from the server as required - as well as heavyweight clients which maintain a full local persistent copy of server state.

API Standards

The mandatory baseline for client-server communication in Matrix is exchanging JSON objects over HTTP APIs. HTTPS is recommended for communication, although HTTP may be supported as a fallback to support basic HTTP clients. More efficient optional transports will in future be supported as optional extensions - e.g. a packed binary encoding over stream-cipher encrypted TCP socket for low-bandwidth/low-roundtrip mobile usage. For the default HTTP transport, all API calls use a Content-Type of application/json. In addition, all strings MUST be encoded as UTF-8.

Clients are authenticated using opaque access_token strings (see Client Authentication for details).

See also Conventions for Matrix APIs in the Appendices for conventions which all Matrix APIs are expected to follow.

Standard error response

Any errors which occur at the Matrix API level MUST return a "standard error response". This is a JSON object which looks like:

{
  "errcode": "<error code>",
  "error": "<error message>"
}

The error string will be a human-readable error message, usually a sentence explaining what went wrong.

The errcode string will be a unique string which can be used to handle an error message e.g. M_FORBIDDEN. Error codes should have their namespace first in ALL CAPS, followed by a single _. For example, if there was a custom namespace com.mydomain.here, and a FORBIDDEN code, the error code should look like COM.MYDOMAIN.HERE_FORBIDDEN. Error codes defined by this specification should start M_.

Some errcodes define additional keys which should be present in the error response object, but the keys error and errcode MUST always be present.

Errors are generally best expressed by their error code rather than the HTTP status code returned. When encountering the error code M_UNKNOWN, clients should prefer the HTTP status code as a more reliable reference for what the issue was. For example, if the client receives an error code of M_NOT_FOUND but the request gave a 400 Bad Request status code, the client should treat the error as if the resource was not found. However, if the client were to receive an error code of M_UNKNOWN with a 400 Bad Request, the client should assume that the request being made was invalid.

Common error codes

These error codes can be returned by any API endpoint:

M_FORBIDDEN Forbidden access, e.g. joining a room without permission, failed login.

M_UNKNOWN_TOKEN The access or refresh token specified was not recognised.

An additional response parameter, soft_logout, might be present on the response for 401 HTTP status codes. See the soft logout section for more information.

M_MISSING_TOKEN No access token was specified for the request.

M_BAD_JSON Request contained valid JSON, but it was malformed in some way, e.g. missing required keys, invalid values for keys.

M_NOT_JSON Request did not contain valid JSON.

M_NOT_FOUND No resource was found for this request.

M_LIMIT_EXCEEDED Too many requests have been sent in a short period of time. Wait a while then try again.

M_UNKNOWN An unknown error has occurred.

Other error codes

The following error codes are specific to certain endpoints.

M_UNRECOGNIZED The server did not understand the request.

M_UNAUTHORIZED The request was not correctly authorized. Usually due to login failures.

M_USER_DEACTIVATED The user ID associated with the request has been deactivated. Typically for endpoints that prove authentication, such as /login.

M_USER_IN_USE Encountered when trying to register a user ID which has been taken.

M_INVALID_USERNAME Encountered when trying to register a user ID which is not valid.

M_ROOM_IN_USE Sent when the room alias given to the createRoom API is already in use.

M_INVALID_ROOM_STATE Sent when the initial state given to the createRoom API is invalid.

M_THREEPID_IN_USE Sent when a threepid given to an API cannot be used because the same threepid is already in use.

M_THREEPID_NOT_FOUND Sent when a threepid given to an API cannot be used because no record matching the threepid was found.

M_THREEPID_AUTH_FAILED Authentication could not be performed on the third party identifier.

M_THREEPID_DENIED The server does not permit this third party identifier. This may happen if the server only permits, for example, email addresses from a particular domain.

M_SERVER_NOT_TRUSTED The client's request used a third party server, e.g. identity server, that this server does not trust.

M_UNSUPPORTED_ROOM_VERSION The client's request to create a room used a room version that the server does not support.

M_INCOMPATIBLE_ROOM_VERSION The client attempted to join a room that has a version the server does not support. Inspect the room_version property of the error response for the room's version.

M_BAD_STATE The state change requested cannot be performed, such as attempting to unban a user who is not banned.

M_GUEST_ACCESS_FORBIDDEN The room or resource does not permit guests to access it.

M_CAPTCHA_NEEDED A Captcha is required to complete the request.

M_CAPTCHA_INVALID The Captcha provided did not match what was expected.

M_MISSING_PARAM A required parameter was missing from the request.

M_INVALID_PARAM A parameter that was specified has the wrong value. For example, the server expected an integer and instead received a string.

M_TOO_LARGE The request or entity was too large.

M_EXCLUSIVE The resource being requested is reserved by an application service, or the application service making the request has not created the resource.

M_RESOURCE_LIMIT_EXCEEDED The request cannot be completed because the homeserver has reached a resource limit imposed on it. For example, a homeserver held in a shared hosting environment may reach a resource limit if it starts using too much memory or disk space. The error MUST have an admin_contact field to provide the user receiving the error a place to reach out to. Typically, this error will appear on routes which attempt to modify state (e.g.: sending messages, account data, etc) and not routes which only read state (e.g.: /sync, get account data, etc).

M_CANNOT_LEAVE_SERVER_NOTICE_ROOM The user is unable to reject an invite to join the server notices room. See the Server Notices module for more information.

The client-server API typically uses HTTP PUT to submit requests with a client-generated transaction identifier. This means that these requests are idempotent. The scope of a transaction identifier is a particular access token. It only serves to identify new requests from retransmits. After the request has finished, the {txnId} value should be changed (how is not specified; a monotonically increasing integer is recommended).

Some API endpoints may allow or require the use of POST requests without a transaction ID. Where this is optional, the use of a PUT request is strongly recommended.

Web Browser Clients

It is realistic to expect that some clients will be written to be run within a web browser or similar environment. In these cases, the homeserver should respond to pre-flight requests and supply Cross-Origin Resource Sharing (CORS) headers on all requests.

Servers MUST expect that clients will approach them with OPTIONS requests, allowing clients to discover the CORS headers. All endpoints in this specification support the OPTIONS method, however the server MUST NOT perform any logic defined for the endpoints when approached with an OPTIONS request.

When a client approaches the server with a request, the server should respond with the CORS headers for that route. The recommended CORS headers to be returned by servers on all requests are:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: X-Requested-With, Content-Type, Authorization

Server Discovery

In order to allow users to connect to a Matrix server without needing to explicitly specify the homeserver's URL or other parameters, clients SHOULD use an auto-discovery mechanism to determine the server's URL based on a user's Matrix ID. Auto-discovery should only be done at login time.

In this section, the following terms are used with specific meanings:

PROMPT Retrieve the specific piece of information from the user in a way which fits within the existing client user experience, if the client is inclined to do so. Failure can take place instead if no good user experience for this is possible at this point.

IGNORE Stop the current auto-discovery mechanism. If no more auto-discovery mechanisms are available, then the client may use other methods of determining the required parameters, such as prompting the user, or using default values.

FAIL_PROMPT Inform the user that auto-discovery failed due to invalid/empty data and PROMPT for the parameter.

FAIL_ERROR Inform the user that auto-discovery did not return any usable URLs. Do not continue further with the current login process. At this point, valid data was obtained, but no server is available to serve the client. No further guess should be attempted and the user should make a conscientious decision what to do next.

Well-known URI

{{% boxes/note %}} Servers hosting the .well-known JSON file SHOULD offer CORS headers, as per the CORS section in this specification. {{% /boxes/note %}}

The .well-known method uses a JSON file at a predetermined location to specify parameter values. The flow for this method is as follows:

Extract the server name from the user's Matrix ID by splitting the Matrix ID at the first colon.
Extract the hostname from the server name.
Make a GET request to https://hostname/.well-known/matrix/client.
1. If the returned status code is 404, then IGNORE.
2. If the returned status code is not 200, or the response body is empty, then FAIL_PROMPT.
3. Parse the response body as a JSON object
  1. If the content cannot be parsed, then FAIL_PROMPT.
4. Extract the base_url value from the m.homeserver property. This value is to be used as the base URL of the homeserver.
  1. If this value is not provided, then FAIL_PROMPT.
5. Validate the homeserver base URL:
  1. Parse it as a URL. If it is not a URL, then FAIL_ERROR.
  2. Clients SHOULD validate that the URL points to a valid homeserver before accepting it by connecting to the /_matrix/client/versions endpoint, ensuring that it does not return an error, and parsing and validating that the data conforms with the expected response format. If any step in the validation fails, then FAIL_ERROR. Validation is done as a simple check against configuration errors, in order to ensure that the discovered address points to a valid homeserver.
  3. It is important to note that the base_url value might include a trailing /. Consumers should be prepared to handle both cases.
6. If the m.identity_server property is present, extract the base_url value for use as the base URL of the identity server. Validation for this URL is done as in the step above, but using /_matrix/identity/v2 as the endpoint to connect to. If the m.identity_server property is present, but does not have a base_url value, then FAIL_PROMPT.

Client Authentication

Most API endpoints require the user to identify themselves by presenting previously obtained credentials in the form of an access_token query parameter or through an Authorization Header of Bearer $access_token. An access token is typically obtained via the Login or Registration processes. Access tokens can expire; a new access token can be generated by using a refresh token.

{{% boxes/note %}} This specification does not mandate a particular format for the access token. Clients should treat it as an opaque byte sequence. Servers are free to choose an appropriate format. Server implementors may like to investigate macaroons. {{% /boxes/note %}}

Using access tokens

Access tokens may be provided in two ways, both of which the homeserver MUST support:

Via a query string parameter, access_token=TheTokenHere.
Via a request header, Authorization: Bearer TheTokenHere.

Clients are encouraged to use the Authorization header where possible to prevent the access token being leaked in access/HTTP logs. The query string should only be used in cases where the Authorization header is inaccessible for the client.

When credentials are required but missing or invalid, the HTTP call will return with a status of 401 and the error code, M_MISSING_TOKEN or M_UNKNOWN_TOKEN respectively. Note that an error code of M_UNKNOWN_TOKEN could mean one of four things:

the access token was never valid.
the access token has been logged out.
the access token has been soft logged out.
{{< added-in v="1.3" >}} the access token needs to be refreshed.

When a client receives an error code of M_UNKNOWN_TOKEN, it should:

attempt to refresh the token, if it has a refresh token;
if soft_logout is set to true, it can offer to re-log in the user, retaining any of the client's persisted information;
otherwise, consider the user as having been logged out.

Relationship between access tokens and devices

Client devices are closely related to access tokens and refresh tokens. Matrix servers should record which device each access token and refresh token are assigned to, so that subsequent requests can be handled correctly. When a refresh token is used to generate a new access token and refresh token, the new access and refresh tokens are now bound to the device associated with the initial refresh token.

By default, the Login and Registration processes auto-generate a new device_id. A client is also free to generate its own device_id or, provided the user remains the same, reuse a device: in either case the client should pass the device_id in the request body. If the client sets the device_id, the server will invalidate any access and refresh tokens previously assigned to that device.

Refreshing access tokens

Access tokens can expire after a certain amount of time. Any HTTP calls that use an expired access token will return with an error code M_UNKNOWN_TOKEN, preferably with soft_logout: true. When a client receives this error and it has a refresh token, it should attempt to refresh the access token by calling /refresh. Clients can also refresh their access token at any time, even if it has not yet expired. If the token refresh succeeds, the client should use the new token for future requests, and can re-try previously-failed requests with the new token. When an access token is refreshed, a new refresh token may be returned; if a new refresh token is given, the old refresh token will be invalidated, and the new refresh token should be used when the access token needs to be refreshed.

The old refresh token remains valid until the new access token or refresh token is used, at which point the old refresh token is revoked. This ensures that if a client fails to receive or persist the new tokens, it will be able to repeat the refresh operation.

If the token refresh fails and the error response included a soft_logout: true property, then the client can treat it as a soft logout and attempt to obtain a new access token by re-logging in. If the error response does not include a soft_logout: true property, the client should consider the user as being logged out.

Handling of clients that do not support refresh tokens is up to the homeserver; clients indicate their support for refresh tokens by including a refresh_token: true property in the request body of the /login and /register endpoints. For example, homeservers may allow the use of non-expiring access tokens, or may expire access tokens anyways and rely on soft logout behaviour on clients that don't support refreshing.

Soft logout

A client can be in a "soft logout" state if the server requires re-authentication before continuing, but does not want to invalidate the client's session. The server indicates that the client is in a soft logout state by including a soft_logout: true parameter in an M_UNKNOWN_TOKEN error response; the soft_logout parameter defaults to false. If the soft_logout parameter is omitted or is false, this means the server has destroyed the session and the client should not reuse it. That is, any persisted state held by the client, such as encryption keys and device information, must not be reused and must be discarded. If soft_logout is true the client can reuse any persisted state.

{{% changed-in v="1.3" %}} A client that receives such a response can try to refresh its access token, if it has a refresh token available. If it does not have a refresh token available, or refreshing fails with soft_logout: true, the client can acquire a new access token by specifying the device ID it is already using to the login API.

User-Interactive Authentication API

Overview

Some API endpoints require authentication that interacts with the user. The homeserver may provide many different ways of authenticating, such as user/password auth, login via a single-sign-on server (SSO), etc. This specification does not define how homeservers should authorise their users but instead defines the standard interface which implementations should follow so that ANY client can log in to ANY homeserver.

The process takes the form of one or more 'stages'. At each stage the client submits a set of data for a given authentication type and awaits a response from the server, which will either be a final success or a request to perform an additional stage. This exchange continues until the final success.

For each endpoint, a server offers one or more 'flows' that the client can use to authenticate itself. Each flow comprises a series of stages, as described above. The client is free to choose which flow it follows, however the flow's stages must be completed in order. Failing to follow the flows in order must result in an HTTP 401 response, as defined below. When all stages in a flow are complete, authentication is complete and the API call succeeds.

User-interactive API in the REST API

In the REST API described in this specification, authentication works by the client and server exchanging JSON dictionaries. The server indicates what authentication data it requires via the body of an HTTP 401 response, and the client submits that authentication data via the auth request parameter.

A client should first make a request with no auth parameter. The homeserver returns an HTTP 401 response, with a JSON body, as follows:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "flows": [
    {
      "stages": [ "example.type.foo", "example.type.bar" ]
    },
    {
      "stages": [ "example.type.foo", "example.type.baz" ]
    }
  ],
  "params": {
      "example.type.baz": {
          "example_key": "foobar"
      }
  },
  "session": "xxxxxx"
}

In addition to the flows, this object contains some extra information:

params: This section contains any information that the client will need to know in order to use a given type of authentication. For each authentication type presented, that type may be present as a key in this dictionary. For example, the public part of an OAuth client ID could be given here.
session: This is a session identifier that the client must pass back to the homeserver, if one is provided, in subsequent attempts to authenticate in the same API call.

The client then chooses a flow and attempts to complete the first stage. It does this by resubmitting the same request with the addition of an auth key in the object that it submits. This dictionary contains a type key whose value is the name of the authentication type that the client is attempting to complete. It must also contain a session key with the value of the session key given by the homeserver, if one was given. It also contains other keys dependent on the auth type being attempted. For example, if the client is attempting to complete auth type example.type.foo, it might submit something like this:

POST /_matrix/client/v3/endpoint HTTP/1.1
Content-Type: application/json

{
  "a_request_parameter": "something",
  "another_request_parameter": "something else",
  "auth": {
      "type": "example.type.foo",
      "session": "xxxxxx",
      "example_credential": "verypoorsharedsecret"
  }
}

If the homeserver deems the authentication attempt to be successful but still requires more stages to be completed, it returns HTTP status 401 along with the same object as when no authentication was attempted, with the addition of the completed key which is an array of auth types the client has completed successfully:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "completed": [ "example.type.foo" ],
  "flows": [
    {
      "stages": [ "example.type.foo", "example.type.bar" ]
    },
    {
      "stages": [ "example.type.foo", "example.type.baz" ]
    }
  ],
  "params": {
      "example.type.baz": {
          "example_key": "foobar"
      }
  },
  "session": "xxxxxx"
}

Individual stages may require more than one request to complete, in which case the response will be as if the request was unauthenticated with the addition of any other keys as defined by the auth type.

If the homeserver decides that an attempt on a stage was unsuccessful, but the client may make a second attempt, it returns the same HTTP status 401 response as above, with the addition of the standard errcode and error fields describing the error. For example:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "errcode": "M_FORBIDDEN",
  "error": "Invalid password",
  "completed": [ "example.type.foo" ],
  "flows": [
    {
      "stages": [ "example.type.foo", "example.type.bar" ]
    },
    {
      "stages": [ "example.type.foo", "example.type.baz" ]
    }
  ],
  "params": {
      "example.type.baz": {
          "example_key": "foobar"
      }
  },
  "session": "xxxxxx"
}

If the request fails for a reason other than authentication, the server returns an error message in the standard format. For example:

HTTP/1.1 400 Bad request
Content-Type: application/json

{
  "errcode": "M_EXAMPLE_ERROR",
  "error": "Something was wrong"
}

If the client has completed all stages of a flow, the homeserver performs the API call and returns the result as normal. Completed stages cannot be retried by clients, therefore servers must return either a 401 response with the completed stages, or the result of the API call if all stages were completed when a client retries a stage.

Some authentication types may be completed by means other than through the Matrix client, for example, an email confirmation may be completed when the user clicks on the link in the email. In this case, the client retries the request with an auth dict containing only the session key. The response to this will be the same as if the client were attempting to complete an auth state normally, i.e. the request will either complete or request auth, with the presence or absence of that auth type in the 'completed' array indicating whether that stage is complete.

{{% boxes/note %}} A request to an endpoint that uses User-Interactive Authentication never succeeds without auth. Homeservers may allow requests that don't require auth by offering a stage with only the m.login.dummy auth type, but they must still give a 401 response to requests with no auth data. {{% /boxes/note %}}

Example

At a high level, the requests made for an API call completing an auth flow with three stages will resemble the following diagram:

    _______________________
    |       Stage 0         |
    | No auth               |
    |  ___________________  |
    | |_Request_1_________| | <-- Returns "session" key which is used throughout.
    |_______________________|
             |
             |
    _________V_____________
    |       Stage 1         |
    | type: "<auth type1>"  |
    |  ___________________  |
    | |_Request_1_________| |
    |_______________________|
             |
             |
    _________V_____________
    |       Stage 2         |
    | type: "<auth type2>"  |
    |  ___________________  |
    | |_Request_1_________| |
    |  ___________________  |
    | |_Request_2_________| |
    |  ___________________  |
    | |_Request_3_________| |
    |_______________________|
             |
             |
    _________V_____________
    |       Stage 3         |
    | type: "<auth type3>"  |
    |  ___________________  |
    | |_Request_1_________| | <-- Returns API response
    |_______________________|

Authentication types

This specification defines the following auth types:

m.login.password
m.login.recaptcha
m.login.sso
m.login.email.identity
m.login.msisdn
m.login.dummy
m.login.registration_token

Password-based

Type	Description
`m.login.password`	The client submits an identifier and secret password, both sent in plain-text.

To use this authentication type, clients should submit an auth dict as follows:

{
  "type": "m.login.password",
  "identifier": {
    ...
  },
  "password": "<password>",
  "session": "<session ID>"
}

where the identifier property is a user identifier object, as described in Identifier types.

For example, to authenticate using the user's Matrix ID, clients would submit:

{
  "type": "m.login.password",
  "identifier": {
    "type": "m.id.user",
    "user": "<user_id or user localpart>"
  },
  "password": "<password>",
  "session": "<session ID>"
}

Alternatively reply using a 3PID bound to the user's account on the homeserver using the /account/3pid_ API rather than giving the user explicitly as follows:

{
  "type": "m.login.password",
  "identifier": {
    "type": "m.id.thirdparty",
    "medium": "<The medium of the third party identifier.>",
    "address": "<The third party address of the user>"
  },
  "password": "<password>",
  "session": "<session ID>"
}

In the case that the homeserver does not know about the supplied 3PID, the homeserver must respond with 403 Forbidden.

Google ReCaptcha

Type	Description
`m.login.recaptcha`	The user completes a Google ReCaptcha 2.0 challenge.

To use this authentication type, clients should submit an auth dict as follows:

{
  "type": "m.login.recaptcha",
  "response": "<captcha response>",
  "session": "<session ID>"
}

Single Sign-On

Type	Description
`m.login.sso`	Authentication is supported by authorising with an external single sign-on provider.

A client wanting to complete authentication using SSO should use the Fallback mechanism. See SSO during User-Interactive Authentication for more information.

Email-based (identity / homeserver)

Type	Description
`m.login.email.identity`	Authentication is supported by authorising an email address with an identity server, or homeserver if supported.

Prior to submitting this, the client should authenticate with an identity server (or homeserver). After authenticating, the session information should be submitted to the homeserver.

To use this authentication type, clients should submit an auth dict as follows:

{
  "type": "m.login.email.identity",
  "threepid_creds": {
    "sid": "<identity server session id>",
    "client_secret": "<identity server client secret>",
    "id_server": "<url of identity server authed with, e.g. 'matrix.org:8090'>",
    "id_access_token": "<access token previously registered with the identity server>"
  },
  "session": "<session ID>"
}

Note that id_server (and therefore id_access_token) is optional if the /requestToken request did not include them.

Phone number/MSISDN-based (identity / homeserver)

Type	Description
`m.login.msisdn`	Authentication is supported by authorising a phone number with an identity server, or homeserver if supported.

Prior to submitting this, the client should authenticate with an identity server (or homeserver). After authenticating, the session information should be submitted to the homeserver.

To use this authentication type, clients should submit an auth dict as follows:

{
  "type": "m.login.msisdn",
  "threepid_creds": {
    "sid": "<identity server session id>",
    "client_secret": "<identity server client secret>",
    "id_server": "<url of identity server authed with, e.g. 'matrix.org:8090'>",
    "id_access_token": "<access token previously registered with the identity server>"
  },
  "session": "<session ID>"
}

Note that id_server (and therefore id_access_token) is optional if the /requestToken request did not include them.

Dummy Auth

Type	Description
`m.login.dummy`	Dummy authentication always succeeds and requires no extra parameters.

The purpose of dummy authentication is to allow servers to not require any form of User-Interactive Authentication to perform a request. It can also be used to differentiate flows where otherwise one flow would be a subset of another flow. e.g. if a server offers flows m.login.recaptcha and m.login.recaptcha, m.login.email.identity and the client completes the recaptcha stage first, the auth would succeed with the former flow, even if the client was intending to then complete the email auth stage. A server can instead send flows m.login.recaptcha, m.login.dummy and m.login.recaptcha, m.login.email.identity to fix the ambiguity.

To use this authentication type, clients should submit an auth dict with just the type and session, if provided:

{
  "type": "m.login.dummy",
  "session": "<session ID>"
}

Token-authenticated registration

Type	Description
`m.login.registration_token`	Registers an account with a pre-shared token for authentication

{{% boxes/note %}} The m.login.registration_token authentication type is only valid on the /register endpoint. {{% /boxes/note %}}

This authentication type provides homeservers the ability to allow registrations to a limited set of people instead of either offering completely open registrations or completely closed registration (where the homeserver administrators create and distribute accounts).

The token required for this authentication type is shared out of band from Matrix and is an opaque string with maximum length of 64 characters in the range [A-Za-z0-9._~-]. The server can keep any number of tokens for any length of time/validity. Such cases might be a token limited to 100 uses or for the next 2 hours - after the tokens expire, they can no longer be used to create accounts.

To use this authentication type, clients should submit an auth dict with just the type, token, and session:

{
  "type": "m.login.registration_token",
  "token": "fBVFdqVE",
  "session": "<session ID>"
}

To determine if a token is valid before attempting to use it, the client can use the /validity API defined below. The API doesn't guarantee that a token will be valid when used, but does avoid cases where the user finds out late in the registration process that their token has expired.

Fallback

Clients cannot be expected to be able to know how to process every single login type. If a client does not know how to handle a given login type, it can direct the user to a web browser with the URL of a fallback page which will allow the user to complete that login step out-of-band in their web browser. The URL it should open is:

/_matrix/client/v3/auth/<auth type>/fallback/web?session=<session ID>

Where auth type is the type name of the stage it is attempting and session ID is the ID of the session given by the homeserver.

This MUST return an HTML page which can perform this authentication stage. This page must use the following JavaScript when the authentication has been completed:

if (window.onAuthDone) {
    window.onAuthDone();
} else if (window.opener && window.opener.postMessage) {
    window.opener.postMessage("authDone", "*");
}

This allows the client to either arrange for the global function onAuthDone to be defined in an embedded browser, or to use the HTML5 cross-document messaging API, to receive a notification that the authentication stage has been completed.

Once a client receives the notification that the authentication stage has been completed, it should resubmit the request with an auth dict with just the session ID:

{
  "session": "<session ID>"
}

Example

A client webapp might use the following JavaScript to open a popup window which will handle unknown login types:

/**
 * Arguments:
 *     homeserverUrl: the base url of the homeserver (e.g. "https://matrix.org")
 *
 *     apiEndpoint: the API endpoint being used (e.g.
 *        "/_matrix/client/v3/account/password")
 *
 *     loginType: the loginType being attempted (e.g. "m.login.recaptcha")
 *
 *     sessionID: the session ID given by the homeserver in earlier requests
 *
 *     onComplete: a callback which will be called with the results of the request
 */
function unknownLoginType(homeserverUrl, apiEndpoint, loginType, sessionID, onComplete) {
    var popupWindow;

    var eventListener = function(ev) {
        // check it's the right message from the right place.
        if (ev.data !== "authDone" || ev.origin !== homeserverUrl) {
            return;
        }

        // close the popup
        popupWindow.close();
        window.removeEventListener("message", eventListener);

        // repeat the request
        var requestBody = {
            auth: {
                session: sessionID,
            },
        };

        request({
            method:'POST', url:apiEndpoint, json:requestBody,
        }, onComplete);
    };

    window.addEventListener("message", eventListener);

    var url = homeserverUrl +
        "/_matrix/client/v3/auth/" +
        encodeURIComponent(loginType) +
        "/fallback/web?session=" +
        encodeURIComponent(sessionID);

   popupWindow = window.open(url);
}

Identifier types

Some authentication mechanisms use a user identifier object to identify a user. The user identifier object has a type field to indicate the type of identifier being used, and depending on the type, has other fields giving the information required to identify the user as described below.

This specification defines the following identifier types:

m.id.user
m.id.thirdparty
m.id.phone

Matrix User ID

Type	Description
`m.id.user`	The user is identified by their Matrix ID.

A client can identify a user using their Matrix ID. This can either be the fully qualified Matrix user ID, or just the localpart of the user ID.

"identifier": {
  "type": "m.id.user",
  "user": "<user_id or user localpart>"
}

Third-party ID

Type	Description
`m.id.thirdparty`	The user is identified by a third-party identifier in canonicalised form.

A client can identify a user using a 3PID associated with the user's account on the homeserver, where the 3PID was previously associated using the /account/3pid_ API. See the 3PID Types Appendix for a list of Third-party ID media.

"identifier": {
  "type": "m.id.thirdparty",
  "medium": "<The medium of the third party identifier>",
  "address": "<The canonicalised third party address of the user>"
}

Phone number

Type	Description
`m.id.phone`	The user is identified by a phone number.

A client can identify a user using a phone number associated with the user's account, where the phone number was previously associated using the /account/3pid_ API. The phone number can be passed in as entered by the user; the homeserver will be responsible for canonicalising it. If the client wishes to canonicalise the phone number, then it can use the m.id.thirdparty identifier type with a medium of msisdn instead.

"identifier": {
  "type": "m.id.phone",
  "country": "<The country that the phone number is from>",
  "phone": "<The phone number>"
}

The country is the two-letter uppercase ISO-3166-1 alpha-2 country code that the number in phone should be parsed as if it were dialled from.

A client can obtain access tokens using the /login API.

Note that this endpoint does not currently use the User-Interactive Authentication API.

For a simple username/password login, clients should submit a /login request as follows:

{
  "type": "m.login.password",
  "identifier": {
    "type": "m.id.user",
    "user": "<user_id or user localpart>"
  },
  "password": "<password>"
}

Alternatively, a client can use a 3PID bound to the user's account on the homeserver using the /account/3pid_ API rather than giving the user explicitly, as follows:

{
  "type": "m.login.password",
  "identifier": {
    "medium": "<The medium of the third party identifier>",
    "address": "<The canonicalised third party address of the user>"
  },
  "password": "<password>"
}

In the case that the homeserver does not know about the supplied 3PID, the homeserver must respond with 403 Forbidden.

To log in using a login token, clients should submit a /login request as follows:

{
  "type": "m.login.token",
  "token": "<login token>"
}

The token must encode the user ID, since there is no other identifying data in the request. In the case that the token is not valid, the homeserver must respond with 403 Forbidden and an error code of M_FORBIDDEN.

If the homeserver advertises m.login.sso as a viable flow, and the client supports it, the client should redirect the user to the /redirect endpoint for client login via SSO. After authentication is complete, the client will need to submit a /login request matching m.login.token.

An appservice can log in by providing a valid appservice token and a user within the appservice's namespace.

{{% boxes/note %}} Appservices do not need to log in as individual users in all cases, as they can perform Identity Assertion using the appservice token. However, if the appservice needs a scoped token for a single user then they can use this API instead. {{% /boxes/note %}}

This request must be authenticated by the appservice as_token (see Client Authentication on how to provide the token).

To use this login type, clients should submit a /login request as follows:

{
  "type": "m.login.application_service",
  "identifier": {
    "type": "m.id.user",
    "user": "<user_id or user localpart>"
  }
}

If the access token is not valid, does not correspond to an appservice or the user has not previously been registered then the homeserver will respond with an errcode of M_FORBIDDEN.

If the access token does correspond to an appservice, but the user id does not lie within its namespace then the homeserver will respond with an errcode of M_EXCLUSIVE.

If a client does not recognize any or all login flows it can use the fallback login API:

GET /_matrix/static/client/login/

This returns an HTML and JavaScript page which can perform the entire login process. The page will attempt to call the JavaScript function window.onLogin when login has been successfully completed.

{{% added-in v="1.1" %}} Non-credential parameters valid for the /login endpoint can be provided as query string parameters here. These are to be forwarded to the login endpoint during the login process. For example:

GET /_matrix/static/client/login/?device_id=GHTYAJCE

Account registration and management

Notes on password management

{{% boxes/warning %}} Clients SHOULD enforce that the password provided is suitably complex. The password SHOULD include a lower-case letter, an upper-case letter, a number and a symbol and be at a minimum 8 characters in length. Servers MAY reject weak passwords with an error code M_WEAK_PASSWORD. {{% /boxes/warning %}}

Adding Account Administrative Contact Information

A homeserver may keep some contact information for administrative use. This is independent of any information kept by any identity servers, though can be proxied (bound) to the identity server in many cases.

{{% boxes/note %}} This section deals with two terms: "add" and "bind". Where "add" (or "remove") is used, it is speaking about an identifier that was not bound to an identity server. As a result, "bind" (or "unbind") references an identifier that is found in an identity server. Note that an identifier can be added and bound at the same time, depending on context. {{% /boxes/note %}}

{{% http-api spec="client-server" api="administrative_contact" %}}

Current account information

Notes on identity servers

Identity servers in Matrix store bindings (relationships) between a user's third party identifier, typically email or phone number, and their user ID. Once a user has chosen an identity server, that identity server should be used by all clients.

Clients can see which identity server the user has chosen through the m.identity_server account data event, as described below. Clients SHOULD refrain from making requests to any identity server until the presence of m.identity_server is confirmed as (not) present. If present, the client SHOULD check for the presence of the base_url property in the event's content. If the base_url is present, the client SHOULD use the identity server in that property as the identity server for the user. If the base_url is missing, or the account data event is not present, the client SHOULD use whichever default value it normally would for an identity server, if applicable. Clients SHOULD NOT update the account data with the default identity server when the user is missing an identity server in their account data.

Clients SHOULD listen for changes to the m.identity_server account data event and update the identity server they are contacting as a result.

If the client offers a way to set the identity server to use, it MUST update the value of m.identity_server accordingly. A base_url of null MUST be treated as though the user does not want to use an identity server, disabling all related functionality as a result.

Clients SHOULD refrain from populating the account data as a migration step for users who are lacking the account data, unless the user sets the identity server within the client to a value. For example, a user which has no m.identity_server account data event should not end up with the client's default identity server in their account data, unless the user first visits their account settings to set the identity server.

Capabilities negotiation

A homeserver may not support certain operations and clients must be able to query for what the homeserver can and can't offer. For example, a homeserver may not support users changing their password as it is configured to perform authentication against an external system.

The capabilities advertised through this system are intended to advertise functionality which is optional in the API, or which depend in some way on the state of the user or server. This system should not be used to advertise unstable or experimental features - this is better done by the /versions endpoint.

Some examples of what a reasonable capability could be are:

Whether the server supports user presence.
Whether the server supports optional features, such as the user or room directories.
The rate limits or file type restrictions imposed on clients by the server.

Some examples of what should not be a capability are:

Whether the server supports a feature in the unstable specification.
Media size limits - these are handled by the /config API.
Optional encodings or alternative transports for communicating with the server.

Capabilities prefixed with m. are reserved for definition in the Matrix specification while other values may be used by servers using the Java package naming convention. The capabilities supported by the Matrix specification are defined later in this section.

`m.change_password` capability

This capability has a single flag, enabled, which indicates whether or not the user can use the /account/password API to change their password. If not present, the client should assume that password changes are possible via the API. When present, clients SHOULD respect the capability's enabled flag and indicate to the user if they are unable to change their password.

An example of the capability API's response for this capability is:

{
  "capabilities": {
    "m.change_password": {
      "enabled": false
    }
  }
}

`m.room_versions` capability

This capability describes the default and available room versions a server supports, and at what level of stability. Clients should make use of this capability to determine if users need to be encouraged to upgrade their rooms.

An example of the capability API's response for this capability is:

{
  "capabilities": {
    "m.room_versions": {
      "default": "1",
      "available": {
        "1": "stable",
        "2": "stable",
        "3": "unstable",
        "custom-version": "unstable"
      }
    }
  }
}

This capability mirrors the same restrictions of room versions to describe which versions are stable and unstable. Clients should assume that the default version is stable. Any version not explicitly labelled as stable in the available versions is to be treated as unstable. For example, a version listed as future-stable should be treated as unstable.

The default version is the version the server is using to create new rooms. Clients should encourage users with sufficient permissions in a room to upgrade their room to the default version when the room is using an unstable version.

When this capability is not listed, clients should use "1" as the default and only stable available room version.

`m.set_displayname` capability

This capability has a single flag, enabled, to denote whether the user is able to change their own display name via profile endpoints. Cases for disabling might include users mapped from external identity/directory services, such as LDAP.

Note that this is well paired with the m.set_avatar_url capability.

When not listed, clients should assume the user is able to change their display name.

An example of the capability API's response for this capability is:

{
  "capabilities": {
    "m.set_displayname": {
      "enabled": false
    }
  }
}

`m.set_avatar_url` capability

This capability has a single flag, enabled, to denote whether the user is able to change their own avatar via profile endpoints. Cases for disabling might include users mapped from external identity/directory services, such as LDAP.

Note that this is well paired with the m.set_displayname capability.

When not listed, clients should assume the user is able to change their avatar.

An example of the capability API's response for this capability is:

{
  "capabilities": {
    "m.set_avatar_url": {
      "enabled": false
    }
  }
}

`m.3pid_changes` capability

This capability has a single flag, enabled, to denote whether the user is able to add, remove, or change 3PID associations on their account. Note that this only affects a user's ability to use the Admin Contact Information API, not endpoints exposed by an Identity Service. Cases for disabling might include users mapped from external identity/directory services, such as LDAP.

When not listed, clients should assume the user is able to modify their 3PID associations.

An example of the capability API's response for this capability is:

{
  "capabilities": {
    "m.3pid_changes": {
      "enabled": false
    }
  }
}

Filtering

Filters can be created on the server and can be passed as a parameter to APIs which return events. These filters alter the data returned from those APIs. Not all APIs accept filters.

Lazy-loading room members

Membership events often take significant resources for clients to track. In an effort to reduce the number of resources used, clients can enable "lazy-loading" for room members. By doing this, servers will attempt to only send membership events which are relevant to the client.

It is important to understand that lazy-loading is not intended to be a perfect optimisation, and that it may not be practical for the server to calculate precisely which membership events are relevant to the client. As a result, it is valid for the server to send redundant membership events to the client to ease implementation, although such redundancy should be minimised where possible to conserve bandwidth.

In terms of filters, lazy-loading is enabled by enabling lazy_load_members on a RoomEventFilter (or a StateFilter in the case of /sync only). When enabled, lazy-loading aware endpoints (see below) will only include membership events for the sender of events being included in the response. For example, if a client makes a /sync request with lazy-loading enabled, the server will only return membership events for the sender of events in the timeline, not all members of a room.

When processing a sequence of events (e.g. by looping on /sync or paginating /messages), it is common for blocks of events in the sequence to share a similar set of senders. Rather than responses in the sequence sending duplicate membership events for these senders to the client, the server MAY assume that clients will remember membership events they have already been sent, and choose to skip sending membership events for members whose membership has not changed. These are called 'redundant membership events'. Clients may request that redundant membership events are always included in responses by setting include_redundant_members to true in the filter.

The expected pattern for using lazy-loading is currently:

Client performs an initial /sync with lazy-loading enabled, and receives only the membership events which relate to the senders of the events it receives.
Clients which support display-name tab-completion or other operations which require rapid access to all members in a room should call /members for the currently selected room, with an ?at parameter set to the /sync response's from token. The member list for the room is then maintained by the state in subsequent incremental /sync responses.
Clients which do not support tab-completion may instead pull in profiles for arbitrary users (e.g. read receipts, typing notifications) on demand by querying the room state or /profile.

The current endpoints which support lazy-loading room members are:

API endpoints

Events

The model of conversation history exposed by the client-server API can be considered as a list of events. The server 'linearises' the eventually-consistent event graph of events into an 'event stream' at any given point in time:

[E0]->[E1]->[E2]->[E3]->[E4]->[E5]

Types of room events

Room events are split into two categories:

State events: These are events which update the metadata state of the room (e.g. room topic, room membership etc). State is keyed by a tuple of event type and a state_key. State in the room with the same key-tuple will be overwritten.
Message events: These are events which describe transient "once-off" activity in a room: typically communication such as sending an instant message or setting up a VoIP call.

This specification outlines several events, all with the event type prefix m.. (See Room Events for the m. event specification.) However, applications may wish to add their own type of event, and this can be achieved using the REST API detailed in the following sections. If new events are added, the event type key SHOULD follow the Java package naming convention, e.g. com.example.myapp.event. This ensures event types are suitably namespaced for each application and reduces the risk of clashes.

{{% boxes/note %}} Events are not limited to the types defined in this specification. New or custom event types can be created on a whim using the Java package naming convention. For example, a com.example.game.score event can be sent by clients and other clients would receive it through Matrix, assuming the client has access to the com.example namespace. {{% /boxes/note %}}

Room event format

The "federation" format of a room event, which is used internally by homeservers and between homeservers via the Server-Server API, depends on the "room version" in use by the room. See, for example, the definitions in room version 1 and room version 3.

However, it is unusual that a Matrix client would encounter this event format. Instead, homeservers are responsible for converting events into the format shown below so that they can be easily parsed by clients.

{{% boxes/warning %}} Event bodies are considered untrusted data. This means that any application using Matrix must validate that the event body is of the expected shape/schema before using the contents verbatim.

It is not safe to assume that an event body will have all the expected fields of the expected types.

See MSC2801 for more detail on why this assumption is unsafe. {{% /boxes/warning %}}

{{% definition path="api/client-server/definitions/client_event" %}}

Stripped state

Stripped state events are simplified state events to help a potential joiner identify the room. These state events can only have the sender, type, state_key and content keys present.

These stripped state events typically appear on invites, knocks, and in other places where a user could join the room under the conditions available (such as a restricted room).

Clients should only use stripped state events so long as they don't have access to the proper state of the room. Once the state of the room is available, all stripped state should be discarded. In cases where the client has an archived state of the room (such as after being kicked) and the client is receiving stripped state for the room, such as from an invite or knock, then the stripped state should take precedence until fresh state can be acquired from a join.

The following state events should be represented as stripped state when possible:

m.room.create
m.room.name
m.room.avatar
m.room.topic
m.room.join_rules
m.room.canonical_alias
m.room.encryption

{{% boxes/note %}} Clients should inspect the list of stripped state events and not assume any particular event is present. The server might include events not described here as well. {{% /boxes/note %}}

{{% boxes/rationale %}} The name, avatar, topic, and aliases are presented as aesthetic information about the room, allowing users to make decisions about whether or not they want to join the room.

The join rules are given to help the client determine why it is able to potentially join. For example, annotating the room decoration with iconography consistent with the respective join rule for the room.

The create event can help identify what kind of room is being joined, as it may be a Space or other kind of room. The client might choose to render the invite in a different area of the application as a result.

Similar to join rules, the encryption information is given to help clients decorate the room with appropriate iconography or messaging. {{% /boxes/rationale %}}

{{% boxes/warning %}} Although stripped state is usually generated and provided by the server, it is still possible to be incorrect on the receiving end. The stripped state events are not signed and could theoretically be modified, or outdated due to updates not being sent. {{% /boxes/warning %}}

Size limits

The complete event MUST NOT be larger than 65536 bytes, when formatted with the federation event format, including any signatures, and encoded as Canonical JSON.

There are additional restrictions on sizes per key:

sender MUST NOT exceed 255 bytes (including domain).
room_id MUST NOT exceed 255 bytes.
state_key MUST NOT exceed 255 bytes.
type MUST NOT exceed 255 bytes.
event_id MUST NOT exceed 255 bytes.

Some event types have additional size restrictions which are specified in the description of the event. Additional keys have no limit other than that implied by the total 64 KiB limit on events.

Room Events

{{% boxes/note %}} This section is a work in progress. {{% /boxes/note %}}

This specification outlines several standard event types, all of which are prefixed with m.

Historical events

Some events within the m. namespace might appear in rooms, however they serve no significant meaning in this version of the specification. They are:

m.room.aliases

Previous versions of the specification have more information on these events.

Syncing

To read events, the intended flow of operation is for clients to first call the /sync API without a since parameter. This returns the most recent message events for each room, as well as the state of the room at the start of the returned timeline. The response also includes a next_batch field, which should be used as the value of the since parameter in the next call to /sync. Finally, the response includes, for each room, a prev_batch field, which can be passed as a start parameter to the /rooms/<room_id>/messages API to retrieve earlier messages.

For example, a /sync request might return a range of four events E2, E3, E4 and E5 within a given room, omitting two prior events E0 and E1. This can be visualised as follows:

    [E0]->[E1]->[E2]->[E3]->[E4]->[E5]
               ^                      ^
               |                      |
         prev_batch: '1-2-3'        next_batch: 'a-b-c'

Clients then receive new events by "long-polling" the homeserver via the /sync API, passing the value of the next_batch field from the response to the previous call as the since parameter. The client should also pass a timeout parameter. The server will then hold open the HTTP connection for a short period of time waiting for new events, returning early if an event occurs. Only the /sync API (and the deprecated /events API) support long-polling in this way.

Continuing the example above, an incremental sync might report a single new event E6. The response can be visualised as:

    [E0]->[E1]->[E2]->[E3]->[E4]->[E5]->[E6]
                                      ^     ^
                                      |     |
                                      |  next_batch: 'x-y-z'
                                    prev_batch: 'a-b-c'

Normally, all new events which are visible to the client will appear in the response to the /sync API. However, if a large number of events arrive between calls to /sync, a "limited" timeline is returned, containing only the most recent message events. A state "delta" is also returned, summarising any state changes in the omitted part of the timeline. The client may therefore end up with "gaps" in its knowledge of the message timeline. The client can fill these gaps using the /rooms/<room_id>/messages API.

Continuing our example, suppose we make a third /sync request asking for events since the last sync, by passing the next_batch token x-y-z as the since parameter. The server knows about four new events, E7, E8, E9 and E10, but decides this is too many to report at once. Instead, the server sends a limited response containing E8, E9 and E10but omitting E7. This forms a gap, which we can see in the visualisation:

                                            | gap |
                                            | <-> |
    [E0]->[E1]->[E2]->[E3]->[E4]->[E5]->[E6]->[E7]->[E8]->[E9]->[E10]
                                            ^     ^                  ^
                                            |     |                  |
                                 since: 'x-y-z'   |                  |
                                       prev_batch: 'd-e-f'       next_batch: 'u-v-w'

The limited response includes a state delta which describes how the state of the room changes over the gap. This delta explains how to build the state prior to returned timeline (i.e. at E7) from the state the client knows (i.e. at E6). To close the gap, the client should make a request to /rooms/<room_id>/messages with the query parameters from=x-y-z and to=d-e-f.

{{% boxes/warning %}} Events are ordered in this API according to the arrival time of the event on the homeserver. This can conflict with other APIs which order events based on their partial ordering in the event graph. This can result in duplicate events being received (once per distinct API called). Clients SHOULD de-duplicate events based on the event ID when this happens. {{% /boxes/warning %}}

{{% boxes/note %}} The /sync API returns a state list which is separate from the timeline. This state list allows clients to keep their model of the room state in sync with that on the server. In the case of an initial (since-less) sync, the state list represents the complete state of the room at the start of the returned timeline (so in the case of a recently-created room whose state fits entirely in the timeline, the state list will be empty).

In the case of an incremental sync, the state list gives a delta between the state of the room at the since parameter and that at the start of the returned timeline. (It will therefore be empty unless the timeline was limited.)

In both cases, it should be noted that the events returned in the state list did not necessarily take place just before the returned timeline, so clients should not display them to the user in the timeline. {{% /boxes/note %}}

{{% boxes/rationale %}} An early design of this specification made the state list represent the room state at the end of the returned timeline, instead of the start. This was unsatisfactory because it led to duplication of events between the state list and the timeline, but more importantly, it made it difficult for clients to show the timeline correctly.

In particular, consider a returned timeline [M0, S1, M2], where M0 and M2 are both messages sent by the same user, and S1 is a state event where that user changes their displayname. If the state list represents the room state at the end of the timeline, the client must take a copy of the state dictionary, and rewind S1, in order to correctly calculate the display name for M0. {{% /boxes/rationale %}}

Getting events for a room

There are several APIs provided to GET events for a room:

Sending events to a room

Servers might need to post-process some events if they relate to another event. The event's relationship type (rel_type) determines any restrictions which might apply, such as the user only being able to send one event of a given type in relation to another. {{% /boxes/note %}}

Examples

Valid requests look like:

PUT /rooms/!roomid:domain/state/m.example.event
{ "key" : "without a state key" }

PUT /rooms/!roomid:domain/state/m.another.example.event/foo
{ "key" : "with 'foo' as the state key" }

In contrast, these requests are invalid:

POST /rooms/!roomid:domain/state/m.example.event/
{ "key" : "cannot use POST here" }

PUT /rooms/!roomid:domain/state/m.another.example.event/foo/11
{ "key" : "txnIds are not supported" }

Care should be taken to avoid setting the wrong state key:

PUT /rooms/!roomid:domain/state/m.another.example.event/11
{ "key" : "with '11' as the state key, but was probably intended to be a txnId" }

The state_key is often used to store state about individual users, by using the user ID as the state_key value. For example:

PUT /rooms/!roomid:domain/state/m.favorite.animal.event/%40my_user%3Aexample.org
{ "animal" : "cat", "reason": "fluffy" }

In some cases, there may be no need for a state_key, so it can be omitted:

PUT /rooms/!roomid:domain/state/m.room.bgd.color
{ "color": "red", "hex": "#ff0000" }

Redactions

Since events are extensible it is possible for malicious users and/or servers to add keys that are, for example offensive or illegal. Since some events cannot be simply deleted, e.g. membership events, we instead 'redact' events. This involves removing all keys from an event that are not required by the protocol. This stripped down event is thereafter returned anytime a client or remote server requests it. Redacting an event cannot be undone, allowing server owners to delete the offending content from the databases. Servers should include a copy of the m.room.redaction event under unsigned as redacted_because when serving the redacted event to clients.

The exact algorithm to apply against an event is defined in the room version specification, as are the criteria homeservers should use when deciding whether to accept a redaction event from a remote homeserver.

When a client receives an m.room.redaction event, it should change the affected event in the same way a server does.

{{% boxes/note %}} Redacted events can still affect the state of the room. When redacted, state events behave as though their properties were simply not specified, except those protected by the redaction algorithm. For example, a redacted join event will still result in the user being considered joined. Similarly, a redacted topic does not necessarily cause the topic to revert to what it was prior to the event - it causes the topic to be removed from the room. {{% /boxes/note %}}

Events

Client behaviour

Forming relationships between events

In some cases it is desirable to logically associate one event's contents with another event's contents — for example, when replying to a message, editing an event, or simply looking to add context for an event's purpose.

Events are related to each other in a parent/child structure, where any event can become a parent by simply having a child event point at it. Parent events do not define their children, instead relying on the children to describe their parent.

The relationship between a child and its parent event is described in the child event's content as m.relates_to (defined below). A child event can point at any other event, including another child event, to build the relationship so long as both events are in the same room, however additional restrictions might be imposed by the type of the relationship (the rel_type).

{{% boxes/note %}} Child events can point at other child events, forming a chain of events. These chains can naturally take the shape of a tree if two independent children point at a single parent event, for example. {{% /boxes/note %}}

To allow the server to aggregate and find child events for a parent, the m.relates_to key of an event MUST be included in the plaintext copy of the event. It cannot be exclusively recorded in the encrypted payload as the server cannot decrypt the event for processing.

{{% boxes/warning %}} If an encrypted event contains an m.relates_to in its payload, it should be ignored and instead favour the plaintext m.relates_to copy (including when there is no plaintext copy). This is to ensure the client's behaviour matches the server's capability to handle relationships. {{% /boxes/warning %}}

Relationships which don't match the schema, or which break the rules of a relationship, are simply ignored. An example might be the parent and child being in different rooms, or the relationship missing properties required by the schema below. Clients handling such invalid relationships should show the events independently of each other, optionally with an error message.

{{% boxes/note %}} While this specification describes an m.relates_to object containing a rel_type, there is not currently any relationship type which uses this structure. Replies, described below, form their relationship outside of the rel_type as a legacy type of relationship. Future versions of the specification might change replies to better match the relationship structures.

Custom rel_types can, and should, still use the schema described above for relevant behaviour. {{% /boxes/note %}}

m.relates_to is defined as follows:

{{% definition path="api/client-server/definitions/m.relates_to" %}}

Relationship types

This specification describes the following relationship types:

Rich replies (Note: does not use rel_type).

Aggregations

Some child events can be "aggregated" by the server, depending on their rel_type. This can allow a set of child events to be summarised to the client without the client needing the child events themselves.

An example of this might be that a rel_type requires an extra key field which, when appropriately specified, would mean that the client receives a total count for the number of times that key was used by child events.

The actual aggregation format depends on the rel_type.

{{% boxes/note %}} This specification does not currently describe any rel_types which require aggregation. This functionality forms a framework for future extensions. {{% /boxes/note %}}

Aggregations are sometimes automatically included by a server alongside the parent event. This is known as a "bundled aggregation" or "bundle" for simplicity. The act of doing this is "bundling".

When an event is served to the client through the APIs listed below, a m.relations property is included under unsigned if the event has child events which can be aggregated and point at it. The m.relations property is an object keyed by rel_type and value being the type-specific aggregated format for that rel_type, also known as the bundle.

For example (unimportant fields not included):

{
  "event_id": "$my_event",
  "unsigned": {
    "m.relations": {
      "org.example.possible_annotations": [
        {
          "key": "👍",
          "origin_server_ts": 1562763768320,
          "count": 3
        },
        {
          "key": "👎",
          "origin_server_ts": 1562763768320,
          "count": 1
        }
      ],
      "org.example.possible_thread": {
        "current_server_participated": true,
        "count": 7,
        "latest_event": {
          "event_id": "$another_event",
          "content": {
            "body": "Hello world"
          }
        }
      }
    }
  }
}

Note how the org.example.possible_annotations bundle is an array compared to the org.example.possible_thread bundle where the server is summarising the state of the relationship in a single object. Both are valid ways to aggregate, and their exact types depend on the rel_type.

{{% boxes/warning %}} State events do not currently receive bundled aggregations. This is not necessarily a deliberate design decision, and MSCs which aim to fix this are welcome. {{% /boxes/warning %}}

The endpoints where the server should include bundled aggregations are:

GET /rooms/{roomId}/messages
GET /rooms/{roomId}/context/{eventId}
GET /rooms/{roomId}/event/{eventId}
GET /rooms/{roomId}/relations/{eventId}
GET /rooms/{roomId}/relations/{eventId}/{relType}
GET /rooms/{roomId}/relations/{eventId}/{relType}/{eventType}
GET /sync when the relevant section has a limited value of true.
POST /search for any matching events under room_events.

{{% boxes/note %}} The server is not required to return bundled aggregations on deprecated endpoints such as /initialSync. {{% /boxes/note %}}

While this functionality allows the client to see what was known to the server at the time of handling, the client should continue to aggregate locally if it is aware of the relationship type's behaviour. For example, a client might increment a count on a parent event's bundle if it saw a new child event which referenced that parent.

The bundle provided by the server only includes child events which were known at the time the client would receive the bundle. For example, in a single /sync response with the parent and multiple child events the child events would have already been included on the parent's m.relations field. Events received in future syncs would need to be aggregated manually by the client.

{{% boxes/note %}} Events from ignored users do not appear in the aggregation from the server, however clients might still have events from ignored users cached. Like with normal events, clients will need to de-aggregate child events sent by ignored users to avoid them being considered in counts. Servers must additionally ensure they do not consider child events from ignored users when preparing a bundle for the client. {{% /boxes/note %}}

When a parent event is redacted, the child events which pointed to that parent remain, however when a child event is redacted then the relationship is broken. Therefore, the server needs to de-aggregate or disassociate the event once the relationship is lost. Clients with local aggregation or which handle redactions locally should do the same.

It is suggested that clients perform local echo on aggregations — for instance, aggregating a new child event into a bundle optimistically until the server returns a failure or the client gives up on sending the event, at which point the event should be de-aggregated and an error or similar shown. The client should be cautious to not aggregate an event twice if it has already optimistically aggregated the event. Clients are encouraged to take this a step further to additionally track child events which target unsent/pending events, likely using the transaction ID as a temporary event ID until a proper event ID is known.

{{% boxes/warning %}} Due to history visibility restrictions, child events might not be visible to the user if they are in a section of history the user cannot see. This means any bundles which would normally include those events will be lacking them and the client will not be able to locally aggregate the events either — relating events of importance (such as votes) should take into consideration history visibility.

Additionally, if the server is missing portions of the room history then it may not be able to accurately aggregate the events. {{% /boxes/warning %}}

Relationships API

To retrieve the child events for a parent from the server, the client can call the following endpoint.

This endpoint is particularly useful if the client has lost context on the aggregation for a parent event and needs to rebuild/verify it.

{{% boxes/note %}} Because replies do not use rel_type, they will not be accessible via this API. {{% /boxes/note %}}

Rooms

Types

Optionally, rooms can have types to denote their intended function. A room without a type does not necessarily mean it has a specific default function, though commonly these rooms will be for conversational purposes.

Room types are best applied when a client might need to differentiate between two different rooms, such as conversation-holding and data-holding. If a room has a type, it is specified in the type key of an m.room.create event. To specify a room's type, provide it as part of creation_content on the create room request.

In this specification the following room types are specified:

m.space

Unspecified room types are permitted through the use of Namespaced Identifiers.

Creation

The homeserver will create an m.room.create event when a room is created, which serves as the root of the event graph for this room. This event also has a creator key which contains the user ID of the room creator. It will also generate several other events in order to manage permissions in this room. This includes:

m.room.power_levels : Sets the power levels of users and required power levels for various actions within the room such as sending events.
m.room.join_rules : Whether the room is "invite-only" or not.

See Room Events for more information on these events. To create a room, a client has to use the following API.

Room aliases

Servers may host aliases for rooms with human-friendly names. Aliases take the form #friendlyname:server.name.

As room aliases are scoped to a particular homeserver domain name, it is likely that a homeserver will reject attempts to maintain aliases on other domain names. This specification does not provide a way for homeservers to send update requests to other servers. However, homeservers MUST handle GET requests to resolve aliases on other servers; they should do this using the federation API if necessary.

Rooms do not store a list of all aliases present on a room, though members of the room with relevant permissions may publish preferred aliases through the m.room.canonical_alias state event. The aliases in the state event should point to the room ID they are published within, however room aliases can and do drift to other room IDs over time. Clients SHOULD NOT treat the aliases as accurate. They SHOULD be checked before they are used or shared with another user. If a room appears to have a room alias of #alias:example.com, this SHOULD be checked to make sure that the room's ID matches the room_id returned from the request.

Permissions

{{% boxes/note %}} This section is a work in progress. {{% /boxes/note %}}

Permissions for rooms are done via the concept of power levels - to do any action in a room a user must have a suitable power level. Power levels are stored as state events in a given room. The power levels required for operations and the power levels for users are defined in m.room.power_levels, where both a default and specific users' power levels can be set. By default all users have a power level of 0, other than the room creator whose power level defaults to 100. Users can grant other users increased power levels up to their own power level. For example, user A with a power level of 50 could increase the power level of user B to a maximum of level 50. Power levels for users are tracked per-room even if the user is not present in the room. The keys contained in m.room.power_levels determine the levels required for certain operations such as kicking, banning and sending state events. See m.room.power_levels for more information.

Clients may wish to assign names to particular power levels. A suggested mapping is as follows: - 0 User - 50 Moderator - 100 Admin

Room membership

Users need to be a member of a room in order to send and receive events in that room. There are several states in which a user may be, in relation to a room:

Unrelated (the user cannot send or receive events in the room)
Knocking (the user has requested to participate in the room, but has not yet been allowed to)
Invited (the user has been invited to participate in the room, but is not yet participating)
Joined (the user can send and receive events in the room)
Banned (the user is not allowed to join the room)

There are a few notable exceptions which allow non-joined members of the room to send events in the room:

Users wishing to reject an invite would send m.room.member events with content.membership of leave. They must have been invited first.
If the room allows, users can send m.room.member events with content.membership of knock to knock on the room. This is a request for an invite by the user.
To retract a previous knock, a user would send a leave event similar to rejecting an invite.

Some rooms require that users be invited to it before they can join; others allow anyone to join. Whether a given room is an "invite-only" room is determined by the room config key m.room.join_rules. It can have one of the following values:

public This room is free for anyone to join without an invite.

invite This room can only be joined if you were invited.

knock This room can only be joined if you were invited, and allows anyone to request an invite to the room. Note that this join rule is only available in room versions which support knocking.

{{% added-in v="1.2" %}} restricted This room can be joined if you were invited or if you are a member of another room listed in the join rules. If the server cannot verify membership for any of the listed rooms then you can only join with an invite. Note that this rule is only expected to work in room versions which support it.

{{% added-in v="1.3" %}} knock_restricted This room can be joined as though it was restricted or knock. If you interact with the room using knocking, the knock rule takes effect whereas trying to join the room without an invite applies the restricted join rule. Note that this rule is only expected to work in room versions which support it.

The allowable state transitions of membership are:

Joining rooms

Knocking on rooms

{{% boxes/note %}} As of v1.3, it is possible to knock on a restricted room if the room supports and is using the knock_restricted join rule.

Note that knock_restricted is only expected to work in room versions which support it. {{% /boxes/note %}}

If the join rules allow, external users to the room can /knock on it to request permission to join. Users with appropriate permissions within the room can then approve (/invite) or deny (/kick, /ban, or otherwise set membership to leave) the knock. Knocks can be retracted by calling /leave or otherwise setting membership to leave.

Users who are currently in the room, already invited, or banned cannot knock on the room.

To accept another user's knock, the user must have permission to invite users to the room. To reject another user's knock, the user must have permission to either kick or ban users (whichever is being performed). Note that setting another user's membership to leave is kicking them.

The knocking homeserver should assume that an invite to the room means that the knock was accepted, even if the invite is not explicitly related to the knock.

Homeservers are permitted to automatically accept invites as a result of knocks as they should be aware of the user's intent to join the room. If the homeserver is not auto-accepting invites (or there was an unrecoverable problem with accepting it), the invite is expected to be passed down normally to the client to handle. Clients can expect to see the join event if the server chose to auto-accept.

Restricted rooms

{{% boxes/note %}} As of v1.3, it is possible to knock on a restricted room if the room supports and is using the knock_restricted join rule.

Note that knock_restricted is only expected to work in room versions which support it. {{% /boxes/note %}}

Restricted rooms are rooms with a join_rule of restricted. These rooms are accompanied by "allow conditions" as described in the m.room.join_rules state event.

If the user has an invite to the room then the restrictions will not affect them. They should be able to join by simply accepting the invite.

When joining without an invite, the server MUST verify that the requesting user meets at least one of the conditions. If no conditions can be verified or no conditions are satisfied, the user will not be able to join. When the join is happening over federation, the remote server will check the conditions before accepting the join. See the Server-Server Spec for more information.

If the room is restricted but no valid conditions are presented then the room is effectively invite only.

The user does not need to maintain the conditions in order to stay a member of the room: the conditions are only checked/evaluated during the join process.

Conditions

Currently there is only one condition available: m.room_membership. This condition requires the user trying to join the room to be a joined member of another room (specifically, the room_id accompanying the condition). For example, if !restricted:example.org wanted to allow joined members of !other:example.org to join, !restricted:example.org would have the following content for m.room.join_rules:

{
  "join_rule": "restricted",
  "allow": [
    {
      "room_id": "!other:example.org",
      "type": "m.room_membership"
    }
  ]
}

Leaving rooms

A user can leave a room to stop receiving events for that room. A user must have been invited to or have joined the room before they are eligible to leave the room. Leaving a room to which the user has been invited rejects the invite, and can retract a knock. Once a user leaves a room, it will no longer appear in the response to the /sync API unless it is explicitly requested via a filter with the include_leave field set to true.

Whether or not they actually joined the room, if the room is an "invite-only" room the user will need to be re-invited before they can re-join the room.

A user can also forget a room which they have left. Rooms which have been forgotten will never appear the response to the /sync API, until the user re-joins, is re-invited, or knocks.

A user may wish to force another user to leave a room. This can be done by 'kicking' the other user. To do so, the user performing the kick MUST have the required power level. Once a user has been kicked, the behaviour is the same as if they had left of their own accord. In particular, the user is free to re-join if the room is not "invite-only".

Banning users in a room

A user may decide to ban another user in a room. 'Banning' forces the target user to leave the room and prevents them from re-joining the room. A banned user will not be treated as a joined user, and so will not be able to send or receive events in the room. In order to ban someone, the user performing the ban MUST have the required power level. To ban a user, a request should be made to /rooms/<room_id>/ban with:

{
  "user_id": "<user id to ban>",
  "reason": "string: <reason for the ban>"
}

Banning a user adjusts the banned member's membership state to ban. Like with other membership changes, a user can directly adjust the target member's state, by making a request to /rooms/<room id>/state/m.room.member/<user id>:

{
  "membership": "ban"
}

A user must be explicitly unbanned with a request to /rooms/<room_id>/unban before they can re-join the room or be re-invited.

Listing rooms

User Data

User Directory

Profiles

Events on Change of Profile Information

Because the profile display name and avatar information are likely to be used in many places of a client's display, changes to these fields cause an automatic propagation event to occur, informing likely-interested parties of the new values. This change is conveyed using two separate mechanisms:

an m.room.member event (with a join membership) is sent to every room the user is a member of, to update the displayname and avatar_url.
an m.presence presence status update is sent, again containing the new values of the displayname and avatar_url keys, in addition to the required presence key containing the current presence state of the user.

Both of these should be done automatically by the homeserver when a user successfully changes their display name or avatar URL fields.

Additionally, when homeservers emit room membership events for their own users, they should include the display name and avatar URL fields in these events so that clients already have these details to hand, and do not have to perform extra round trips to query it.

Security

Rate limiting

Homeservers SHOULD implement rate limiting to reduce the risk of being overloaded. If a request is refused due to rate limiting, it should return a standard error response of the form:

{
  "errcode": "M_LIMIT_EXCEEDED",
  "error": "string",
  "retry_after_ms": integer (optional)
}

The retry_after_ms key SHOULD be included to tell the client how long they have to wait in milliseconds before they can try again.

Modules

Modules are parts of the Client-Server API which are not universal to all endpoints. Modules are strictly defined within this specification and should not be mistaken for experimental extensions or optional features. A compliant server implementation MUST support all modules and supporting specification (unless the implementation only targets clients of certain profiles, in which case only the required modules for those feature profiles MUST be implemented). A compliant client implementation MUST support all the required modules and supporting specification for the Feature Profile it targets.

Feature Profiles

Matrix supports many different kinds of clients: from embedded IoT devices to desktop clients. Not all clients can provide the same feature sets as other clients e.g. due to lack of physical hardware such as not having a screen. Clients can fall into one of several profiles and each profile contains a set of features that the client MUST support. This section details a set of "feature profiles". Clients are expected to implement a profile in its entirety in order for it to be classified as that profile.

Summary

Module / Profile	Web	Mobile	Desktop	CLI	Embedded
Instant Messaging	Required	Required	Required	Required	Optional
Rich replies	Optional	Optional	Optional	Optional	Optional
Direct Messaging	Required	Required	Required	Required	Optional
Mentions	Required	Required	Required	Optional	Optional
Presence	Required	Required	Required	Required	Optional
Push Notifications	Optional	Required	Optional	Optional	Optional
Receipts	Required	Required	Required	Required	Optional
Fully read markers	Optional	Optional	Optional	Optional	Optional
Typing Notifications	Required	Required	Required	Required	Optional
VoIP	Required	Required	Required	Optional	Optional
Ignoring Users	Required	Required	Required	Optional	Optional
Reporting Content	Optional	Optional	Optional	Optional	Optional
Content Repository	Required	Required	Required	Optional	Optional
Managing History Visibility	Required	Required	Required	Required	Optional
Server Side Search	Optional	Optional	Optional	Optional	Optional
Room Upgrades	Required	Required	Required	Required	Optional
Server Administration	Optional	Optional	Optional	Optional	Optional
Event Context	Optional	Optional	Optional	Optional	Optional
Third Party Networks	Optional	Optional	Optional	Optional	Optional
Send-to-Device Messaging	Optional	Optional	Optional	Optional	Optional
Device Management	Optional	Optional	Optional	Optional	Optional
End-to-End Encryption	Optional	Optional	Optional	Optional	Optional
Guest Accounts	Optional	Optional	Optional	Optional	Optional
Room Previews	Optional	Optional	Optional	Optional	Optional
Client Config	Optional	Optional	Optional	Optional	Optional
SSO Login	Optional	Optional	Optional	Optional	Optional
OpenID	Optional	Optional	Optional	Optional	Optional
Stickers	Optional	Optional	Optional	Optional	Optional
Server ACLs	Optional	Optional	Optional	Optional	Optional
Server Notices	Optional	Optional	Optional	Optional	Optional
Moderation policies	Optional	Optional	Optional	Optional	Optional
Spaces	Optional	Optional	Optional	Optional	Optional

Please see each module for more details on what clients need to implement.

Clients

Stand-alone web (`Web`)

This is a web page which heavily uses Matrix for communication. Single-page web apps would be classified as a stand-alone web client, as would multi-page web apps which use Matrix on nearly every page.

Mobile (`Mobile`)

This is a Matrix client specifically designed for consumption on mobile devices. This is typically a mobile app but need not be so provided the feature set can be reached (e.g. if a mobile site could display push notifications it could be classified as a mobile client).

Desktop (`Desktop`)

This is a native GUI application which can run in its own environment outside a browser.

Command Line Interface (`CLI`)

This is a client which is used via a text-based terminal.

Embedded (`Embedded`)

This is a client which is embedded into another application or an embedded device.

Application

This is a Matrix client which is embedded in another website, e.g. using iframes. These embedded clients are typically for a single purpose related to the website in question, and are not intended to be fully-fledged communication apps.

Device

This is a client which is typically running on an embedded device such as a kettle, fridge or car. These clients tend to perform a few operations and run in a resource constrained environment. Like embedded applications, they are not intended to be fully-fledged communication systems.

{{% cs-module name="instant_messaging" %}} {{% cs-module name="rich_replies" %}} {{% cs-module name="voip_events" %}} {{% cs-module name="typing_notifications" %}} {{% cs-module name="receipts" %}} {{% cs-module name="read_markers" %}} {{% cs-module name="presence" %}} {{% cs-module name="content_repo" %}} {{% cs-module name="send_to_device" %}} {{% cs-module name="device_management" %}} {{% cs-module name="end_to_end_encryption" %}} {{% cs-module name="secrets" %}} {{% cs-module name="history_visibility" %}} {{% cs-module name="push" %}} {{% cs-module name="third_party_invites" %}} {{% cs-module name="search" %}} {{% cs-module name="guest_access" %}} {{% cs-module name="room_previews" %}} {{% cs-module name="tags" %}} {{% cs-module name="account_data" %}} {{% cs-module name="admin" %}} {{% cs-module name="event_context" %}} {{% cs-module name="sso_login" %}} {{% cs-module name="dm" %}} {{% cs-module name="ignore_users" %}} {{% cs-module name="stickers" %}} {{% cs-module name="report_content" %}} {{% cs-module name="third_party_networks" %}} {{% cs-module name="openid" %}} {{% cs-module name="server_acls" %}} {{% cs-module name="mentions" %}} {{% cs-module name="room_upgrades" %}} {{% cs-module name="server_notices" %}} {{% cs-module name="moderation_policies" %}} {{% cs-module name="spaces" %}}

102 KiB Raw Blame History

API Standards

Standard error response

Common error codes

Other error codes

Web Browser Clients

Server Discovery

Well-known URI

Client Authentication

Using access tokens

Relationship between access tokens and devices

Refreshing access tokens

Soft logout

User-Interactive Authentication API

Overview

User-interactive API in the REST API

Example

Authentication types

Password-based

Google ReCaptcha

Single Sign-On

Email-based (identity / homeserver)

Phone number/MSISDN-based (identity / homeserver)

Dummy Auth

Token-authenticated registration

Fallback

Example

Identifier types

Matrix User ID

Third-party ID

Phone number

Login

Appservice Login

Login Fallback

Account registration and management

Notes on password management

Adding Account Administrative Contact Information

Current account information

Notes on identity servers

Capabilities negotiation

m.change_password capability

m.room_versions capability

m.set_displayname capability

m.set_avatar_url capability

m.3pid_changes capability

Filtering

Lazy-loading room members

API endpoints

Events

Types of room events

Room event format

Stripped state

Size limits

Room Events

Historical events

Syncing

Getting events for a room

Sending events to a room

Redactions

Events

Client behaviour

Forming relationships between events

Relationship types

Aggregations

Relationships API

Rooms

Types

Creation

Room aliases

Permissions

Room membership

Joining rooms

Knocking on rooms

Restricted rooms

Conditions

Leaving rooms

Banning users in a room

Listing rooms

User Data

User Directory

102 KiB

Raw Blame History

`m.change_password` capability

`m.room_versions` capability

`m.set_displayname` capability

`m.set_avatar_url` capability

`m.3pid_changes` capability

Stand-alone web (`Web`)

Mobile (`Mobile`)

Desktop (`Desktop`)

Command Line Interface (`CLI`)

Embedded (`Embedded`)