The client-server API provides a simple lightweight API to let clients 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.
Table of Contents
Version: r0.6.0
Breaking Changes
New Endpoints
Backwards Compatible Changes
Spec Clarifications
This version of the specification is generated from matrix-doc as of Git commit client_server/release-r0.6.0,5b6d6fe4.
For the full historical changelog, see https://github.com/matrix-org/matrix-doc/blob/main/changelogs/legacy/client_server.rst
The following other versions are also available, in reverse chronological order:
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), passed as a query string parameter on all requests.
The names of the API endpoints for the HTTP transport follow a convention of using underscores to separate words (for example /delete_devices). The key names in JSON objects passed over the API also follow this convention.
Note
There are a few historical exceptions to this rule, such as /createRoom. A future version of this specification will address the inconsistency.
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. These error codes should have their namespace first in ALL CAPS, followed by a single _ to ease separating the namespace from the error code. 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. There may be additional keys depending on the error, 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.
The common error codes are:
| M_FORBIDDEN: | Forbidden access, e.g. joining a room without permission, failed login. |
|---|---|
| M_UNKNOWN_TOKEN: | |
| The access token specified was not recognised. | |
| 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 client might encounter are:
| 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, eg. 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 (eg: sending messages, account data, etc) and not routes which only read state (eg: /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.
Gets the versions of the specification supported by the server.
Values will take the form rX.Y.Z.
Only the latest Z value will be reported for each supported X.Y value. i.e. if the server implements r0.0.0, r0.0.1, and r1.2.0, it will report r0.0.1 and r1.2.0.
The server may additionally advertise experimental features it supports through unstable_features. These features should be namespaced and may optionally include version information within their name if desired. Features listed here are not for optionally toggling parts of the Matrix specification and should only be used to advertise support for a feature which has not yet landed in the spec. For example, a feature currently undergoing the proposal process may appear here and eventually be taken off this list once the feature lands in the spec and the server deems it reasonable to do so. Servers may wish to keep advertising features here after they've been released into the spec to give clients a chance to upgrade appropriately. Additionally, clients should avoid using unstable features in their stable releases.
| Rate-limited: | No. |
|---|---|
| Requires auth: | No. |
Request format:
No parameters
Response format:
| Parameter | Type | Description |
|---|---|---|
| versions | [string] | Required. The supported versions. |
| unstable_features | {string: boolean} | Experimental features the server supports. Features not listed here, or the lack of this property all together, indicate that a feature is not supported. |
Example request:
GET /_matrix/client/versions HTTP/1.1
Response:
Status code 200:
The versions supported by the server.
Example
{ "versions": [ "r0.0.1" ], "unstable_features": { "org.example.my_feature": true } }
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 s upport 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: Origin, X-Requested-With, Content-Type, Accept, Authorization
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:
Note
Servers hosting the .well-known JSON file SHOULD offer CORS headers, as per the CORS section in this specification.
The .well-known method uses a JSON file at a predetermined location to specify parameter values. The flow for this method is as follows:
Gets discovery information about the domain. The file may include additional keys, which MUST follow the Java package naming convention, e.g. com.example.myapp.property. This ensures property names are suitably namespaced for each application and reduces the risk of clashes.
Note that this endpoint is not necessarily handled by the homeserver, but by another webserver, to be used for discovering the homeserver URL.
| Rate-limited: | No. |
|---|---|
| Requires auth: | No. |
Request format:
No parameters
Response format:
| Parameter | Type | Description |
|---|---|---|
| m.homeserver | Homeserver Information | Required. Used by clients to discover homeserver information. |
| m.identity_server | Identity Server Information | Used by clients to discover identity server information. |
| Parameter | Type | Description |
|---|---|---|
| base_url | string | Required. The base URL for the homeserver for client-server connections. |
| Parameter | Type | Description |
|---|---|---|
| base_url | string | Required. The base URL for the identity server for client-server connections. |
Example request:
GET /.well-known/matrix/client HTTP/1.1
Responses:
Status code 200:
Server discovery information.
Example
{ "m.homeserver": { "base_url": "https://matrix.example.com" }, "m.identity_server": { "base_url": "https://identity.example.com" }, "org.example.custom.property": { "app_url": "https://custom.app.example.org" } }
Status code 404:
No server discovery information available.
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.
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.
Access tokens may be provided in two ways, both of which the homeserver MUST support:
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.
Client devices are closely related to access tokens. Matrix servers should record which device each access token is assigned to, so that subsequent requests can be handled correctly.
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 token previously assigned to that device. There is therefore at most one active access token assigned to each device at any one time.
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 social network (OAuth2), login by confirming a token sent to their email address, 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 login 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.
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 [1]. 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:
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/r0/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.
| [1] | 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. |
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 |_______________________|
| Type: | m.login.password |
|---|---|
| Description: | 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 then 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.
| Type: | m.login.recaptcha |
|---|---|
| Description: | 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>" }
| Type: | m.login.token |
|---|---|
| Description: | The client submits a login token. |
To use this authentication type, clients should submit an auth dict as follows:
{ "type": "m.login.token", "token": "<token>", "txn_id": "<client generated nonce>", "session": "<session ID>" }
The nonce should be a random string generated by the client for the request. The same nonce should be used if retrying the request.
A client may receive a login token via some external service, such as email or SMS. Note that a login token is separate from an access token, the latter providing general authentication to various API endpoints.
The txn_id may be used by the server to disallow other devices from using the token, thus providing "single use" tokens while still allowing the device to retry the request. This would be done by tying the token to the txn_id server side, as well as potentially invalidating the token completely once the device has successfully logged in (e.g. when we receive a request from the newly provisioned access_token).
The server must encode the user id in the token. There is therefore no need for the client to submit a separate username.
| Type: | m.login.oauth2 |
|---|---|
| Description: | Authentication is supported via OAuth2 URLs. This login consists of multiple requests. |
| Parameters: | uri: Authorization Request URI OR service selection URI. Both contain an encoded redirect URI. |
The homeserver acts as a 'confidential' client for the purposes of OAuth2. If the uri is a service selection URI, it MUST point to a webpage which prompts the user to choose which service to authorize with. On selection of a service, this MUST link through to an Authorization Request URI. If there is only one service which the homeserver accepts when logging in, this indirection can be skipped and the "uri" key can be the Authorization Request URI.
The client then visits the Authorization Request URI, which then shows the OAuth2 Allow/Deny prompt. Hitting 'Allow' redirects to the redirect URI with the auth code. Homeservers can choose any path for the redirect URI. Once the OAuth flow has completed, the client retries the request with the session only, as above.
| Type: | m.login.email.identity |
|---|---|
| Description: | 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", "threepidCreds": [ { "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.
| Type: | m.login.msisdn |
|---|---|
| Description: | 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", "threepidCreds": [ { "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.
| Type: | m.login.dummy |
|---|---|
| Description: | Dummy authentication always succeeds and requires no extra parameters. Its purpose 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. eg. 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>" }
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/r0/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 notificaton that the authentication stage has been completed, it should resubmit the request with an auth dict with just the session ID:
{ "session": "<session ID>" }
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 (eg "https://matrix.org") * * apiEndpoint: the API endpoint being used (eg * "/_matrix/client/r0/account/password") * * loginType: the loginType being attempted (eg "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:apiEndpint, json:requestBody, }, onComplete); }; window.addEventListener("message", eventListener); var url = homeserverUrl + "/_matrix/client/r0/auth/" + encodeURIComponent(loginType) + "/fallback/web?session=" + encodeURIComponent(sessionID); popupWindow = window.open(url); }
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.
| Type: | m.id.user |
|---|---|
| Description: | 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>" }
| Type: | m.id.thirdparty |
|---|---|
| Description: | 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>" }
| Type: | m.id.phone |
|---|---|
| Description: | 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 then 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>" }
As with token-based interactive login, the token must encode the user ID. 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 Single Sign-On. After authentication is complete, the client will need to submit a /login request matching m.login.token.
Gets the homeserver's supported login types to authenticate users. Clients should pick one of these and supply it as the type when logging in.
| Rate-limited: | Yes. |
|---|---|
| Requires auth: | No. |
Request format:
No parameters
Response format:
| Parameter | Type | Description |
|---|---|---|
| flows | [LoginFlow] | The homeserver's supported login types |
| Parameter | Type | Description |
|---|---|---|
| type | string | The login type. This is supplied as the type when logging in. |
Example request:
GET /_matrix/client/r0/login HTTP/1.1
Responses:
Status code 200:
The login types the homeserver supports
Example
{ "flows": [ { "type": "m.login.password" } ] }
Status code 429:
This request was rate-limited.
Example
{ "errcode": "M_LIMIT_EXCEEDED", "error": "Too many requests", "retry_after_ms": 2000 }
Authenticates the user, and issues an access token they can use to authorize themself in subsequent requests.
If the client does not supply a device_id, the server must auto-generate one.
The returned access token must be associated with the device_id supplied by the client or generated by the server. The server may invalidate any access token previously associated with that device. See Relationship between access tokens and devices.
| Rate-limited: | Yes. |
|---|---|
| Requires auth: | No. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| JSON body parameters | ||
| type | enum | Required. The login type being used. One of: ["m.login.password", "m.login.token"] |
| identifier | User identifier | Identification information for the user. |
| user | string | The fully qualified user ID or just local part of the user ID, to log in. Deprecated in favour of identifier. |
| medium | string | When logging in using a third party identifier, the medium of the identifier. Must be 'email'. Deprecated in favour of identifier. |
| address | string | Third party identifier for the user. Deprecated in favour of identifier. |
| password | string | Required when type is m.login.password. The user's password. |
| token | string | Required when type is m.login.token. Part of Token-based login. |
| device_id | string | ID of the client device. If this does not correspond to a known client device, a new device will be created. The server will auto-generate a device_id if this is not specified. |
| initial_device_display_name | string | A display name to assign to the newly-created device. Ignored if device_id corresponds to a known device. |
| Parameter | Type | Description |
|---|---|---|
| type | string | Required. The type of identification. See Identifier types for supported values and additional property descriptions. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| user_id | string | The fully-qualified Matrix ID that has been registered. |
| access_token | string | An access token for the account. This access token can then be used to authorize other requests. |
| home_server | string | The server_name of the homeserver on which the account has been registered. Deprecated. Clients should extract the server_name from user_id (by splitting at the first colon) if they require it. Note also that homeserver is not spelt this way. |
| device_id | string | ID of the logged-in device. Will be the same as the corresponding parameter in the request, if one was specified. |
| well_known | Discovery Information | Optional client configuration provided by the server. If present, clients SHOULD use the provided object to reconfigure themselves, optionally validating the URLs within. This object takes the same form as the one returned from .well-known autodiscovery. |
| Parameter | Type | Description |
|---|---|---|
| m.homeserver | Homeserver Information | Required. Used by clients to discover homeserver information. |
| m.identity_server | Identity Server Information | Used by clients to discover identity server information. |
| Parameter | Type | Description |
|---|---|---|
| base_url | string | Required. The base URL for the homeserver for client-server connections. |
| Parameter | Type | Description |
|---|---|---|
| base_url | string | Required. The base URL for the identity server for client-server connections. |
Example request:
POST /_matrix/client/r0/login HTTP/1.1 Content-Type: application/json { "type": "m.login.password", "identifier": { "type": "m.id.user", "user": "cheeky_monkey" }, "password": "ilovebananas", "initial_device_display_name": "Jungle Phone" }
Responses:
Status code 200:
The user has been authenticated.
Example
{ "user_id": "@cheeky_monkey:matrix.org", "access_token": "abc123", "device_id": "GHTYAJCE", "well_known": { "m.homeserver": { "base_url": "https://example.org" }, "m.identity_server": { "base_url": "https://id.example.org" } } }
Status code 400:
Part of the request was invalid. For example, the login type may not be recognised.
Example
{ "errcode": "M_UNKNOWN", "error": "Bad login type." }
Status code 403:
Example
{ "errcode": "M_FORBIDDEN" }
Status code 429:
This request was rate-limited.
Example
{ "errcode": "M_LIMIT_EXCEEDED", "error": "Too many requests", "retry_after_ms": 2000 }
Invalidates an existing access token, so that it can no longer be used for authorization. The device associated with the access token is also deleted. Device keys for the device are deleted alongside the device.
| Rate-limited: | No. |
|---|---|
| Requires auth: | Yes. |
Request format:
No parameters
Example request:
POST /_matrix/client/r0/logout HTTP/1.1
Response:
Status code 200:
The access token used in the request was succesfully invalidated.
Example
{}
Invalidates all access tokens for a user, so that they can no longer be used for authorization. This includes the access token that made this request. All devices for the user are also deleted. Device keys for the device are deleted alongside the device.
This endpoint does not require UI authorization because UI authorization is designed to protect against attacks where the someone gets hold of a single access token then takes over the account. This endpoint invalidates all access tokens for the user, including the token used in the request, and therefore the attacker is unable to take over the account in this way.
| Rate-limited: | No. |
|---|---|
| Requires auth: | Yes. |
Request format:
No parameters
Example request:
POST /_matrix/client/r0/logout/all HTTP/1.1
Response:
Status code 200:
The user's access tokens were succesfully invalidated.
Example
{}
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.
This API endpoint uses the User-Interactive Authentication API, except in the cases where a guest account is being registered.
Register for an account on this homeserver.
There are two kinds of user account:
If registration is successful, this endpoint will issue an access token the client can use to authorize itself in subsequent requests.
If the client does not supply a device_id, the server must auto-generate one.
The server SHOULD register an account with a User ID based on the username provided, if any. Note that the grammar of Matrix User ID localparts is restricted, so the server MUST either map the provided username onto a user_id in a logical manner, or reject usernames which do not comply to the grammar, with M_INVALID_USERNAME.
Matrix clients MUST NOT assume that localpart of the registered user_id matches the provided username.
The returned access token must be associated with the device_id supplied by the client or generated by the server. The server may invalidate any access token previously associated with that device. See Relationship between access tokens and devices.
When registering a guest account, all parameters in the request body with the exception of initial_device_display_name MUST BE ignored by the server. The server MUST pick a device_id for the account regardless of input.
Any user ID returned by this API must conform to the grammar given in the Matrix specification.
| Rate-limited: | Yes. |
|---|---|
| Requires auth: | No. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| query parameters | ||
| kind | enum | The kind of account to register. Defaults to user. One of: ["guest", "user"] |
| JSON body parameters | ||
| auth | Authentication Data | Additional authentication information for the user-interactive authentication API. Note that this information is not used to define how the registered user should be authenticated, but is instead used to authenticate the register call itself. |
| username | string | The basis for the localpart of the desired Matrix ID. If omitted, the homeserver MUST generate a Matrix ID local part. |
| password | string | The desired password for the account. |
| device_id | string | ID of the client device. If this does not correspond to a known client device, a new device will be created. The server will auto-generate a device_id if this is not specified. |
| initial_device_display_name | string | A display name to assign to the newly-created device. Ignored if device_id corresponds to a known device. |
| inhibit_login | boolean | If true, an access_token and device_id should not be returned from this call, therefore preventing an automatic login. Defaults to false. |
| Parameter | Type | Description |
|---|---|---|
| type | string | Required. The login type that the client is attempting to complete. |
| session | string | The value of the session key given by the homeserver. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| user_id | string | Required. The fully-qualified Matrix user ID (MXID) that has been registered. Any user ID returned by this API must conform to the grammar given in the Matrix specification. |
| access_token | string | An access token for the account. This access token can then be used to authorize other requests. Required if the inhibit_login option is false. |
| home_server | string | The server_name of the homeserver on which the account has been registered. Deprecated. Clients should extract the server_name from user_id (by splitting at the first colon) if they require it. Note also that homeserver is not spelt this way. |
| device_id | string | ID of the registered device. Will be the same as the corresponding parameter in the request, if one was specified. Required if the inhibit_login option is false. |
Example request:
POST /_matrix/client/r0/register?kind=user HTTP/1.1 Content-Type: application/json { "auth": { "type": "example.type.foo", "session": "xxxxx", "example_credential": "verypoorsharedsecret" }, "username": "cheeky_monkey", "password": "ilovebananas", "device_id": "GHTYAJCE", "initial_device_display_name": "Jungle Phone", "inhibit_login": false }
Responses:
Status code 200:
The account has been registered.
Example
{ "user_id": "@cheeky_monkey:matrix.org", "access_token": "abc123", "device_id": "GHTYAJCE" }
Status code 400:
Part of the request was invalid. This may include one of the following error codes:
These errors may be returned at any stage of the registration process, including after authentication if the requested user ID was registered whilst the client was performing authentication.
Homeservers MUST perform the relevant checks and return these codes before performing User-Interactive Authentication, although they may also return them after authentication is completed if, for example, the requested user ID was registered whilst the client was performing authentication.
Example
{ "errcode": "M_USER_IN_USE", "error": "Desired user ID is already taken." }
Status code 401:
The homeserver requires additional authentication information.
Example
{ "flows": [ { "stages": [ "example.type.foo" ] } ], "params": { "example.type.baz": { "example_key": "foobar" } }, "session": "xxxxxxyz", "completed": [ "example.type.foo" ] }
Status code 403:
The homeserver does not permit registering the account. This response can be used to identify that a particular kind of account is not allowed, or that registration is generally not supported by the homeserver.
Example
{ "errcode": "M_FORBIDDEN", "error": "Registration is disabled" }
Status code 429:
This request was rate-limited.
Example
{ "errcode": "M_LIMIT_EXCEEDED", "error": "Too many requests", "retry_after_ms": 2000 }
The homeserver must check that the given email address is not already associated with an account on this homeserver. The homeserver should validate the email itself, either by sending a validation email itself or by using a service it has control over.
| Rate-limited: | No. |
|---|---|
| Requires auth: | No. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| JSON body parameters | ||
| client_secret | string | Required. A unique string generated by the client, and used to identify the validation attempt. It must be a string consisting of the characters [0-9a-zA-Z.=_-]. Its length must not exceed 255 characters and it must not be empty. |
| string | Required. The email address to validate. | |
| send_attempt | integer | Required. The server will only send an email if the send_attempt is a number greater than the most recent one which it has seen, scoped to that email + client_secret pair. This is to avoid repeatedly sending the same email in the case of request retries between the POSTing user and the identity server. The client should increment this value if they desire a new email (e.g. a reminder) to be sent. If they do not, the server should respond with success but not resend the email. |
| next_link | string | Optional. When the validation is completed, the identity server will redirect the user to this URL. This option is ignored when submitting 3PID validation information through a POST request. |
| id_server | string | The hostname of the identity server to communicate with. May optionally include a port. This parameter is ignored when the homeserver handles 3PID verification. This parameter is deprected with a plan to be removed in a future specification version for /account/password and /register requests. |
| id_access_token | string | An access token previously registered with the identity server. Servers can treat this as optional to distinguish between r0.5-compatible clients and this specification version. Required if an id_server is supplied. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| sid | string | Required. The session ID. Session IDs are opaque strings that must consist entirely of the characters [0-9a-zA-Z.=_-]. Their length must not exceed 255 characters and they must not be empty. |
| submit_url | string | An optional field containing a URL where the client must submit the validation token to, with identical parameters to the Identity Service API's POST /validate/email/submitToken endpoint (without the requirement for an access token). The homeserver must send this token to the user (if applicable), who should then be prompted to provide it to the client. If this field is not present, the client can assume that verification will happen without the client's involvement provided the homeserver advertises this specification version in the /versions response (ie: r0.5.0). |
Example request:
POST /_matrix/client/r0/register/email/requestToken HTTP/1.1 Content-Type: application/json { "client_secret": "monkeys_are_GREAT", "email"<EMAIL_ADDRESS>"send_attempt": 1, "next_link": "https://example.org/congratulations.html", "id_server": "id.example.com", "id_access_token": "string" }
Responses:
Status code 200:
An email has been sent to the specified address. Note that this may be an email containing the validation token or it may be informing the user of an error.
Example
{ "sid": "123abc", "submit_url": "https://example.org/path/to/submitToken" }
Status code 400:
Part of the request was invalid. This may include one of the following error codes:
Example
{ "errcode": "M_THREEPID_IN_USE", "error": "The specified address is already in use" }
Status code 403:
The homeserver does not permit the address to be bound.
Example
{ "errcode": "M_THREEPID_DENIED", "error": "Third party identifier is not allowed" }
The homeserver must check that the given phone number is not already associated with an account on this homeserver. The homeserver should validate the phone number itself, either by sending a validation message itself or by using a service it has control over.
| Rate-limited: | No. |
|---|---|
| Requires auth: | No. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| JSON body parameters | ||
| client_secret | string | Required. A unique string generated by the client, and used to identify the validation attempt. It must be a string consisting of the characters [0-9a-zA-Z.=_-]. Its length must not exceed 255 characters and it must not be empty. |
| country | string | Required. The two-letter uppercase ISO-3166-1 alpha-2 country code that the number in phone_number should be parsed as if it were dialled from. |
| phone_number | string | Required. The phone number to validate. |
| send_attempt | integer | Required. The server will only send an SMS if the send_attempt is a number greater than the most recent one which it has seen, scoped to that country + phone_number + client_secret triple. This is to avoid repeatedly sending the same SMS in the case of request retries between the POSTing user and the identity server. The client should increment this value if they desire a new SMS (e.g. a reminder) to be sent. |
| next_link | string | Optional. When the validation is completed, the identity server will redirect the user to this URL. This option is ignored when submitting 3PID validation information through a POST request. |
| id_server | string | The hostname of the identity server to communicate with. May optionally include a port. This parameter is ignored when the homeserver handles 3PID verification. This parameter is deprected with a plan to be removed in a future specification version for /account/password and /register requests. |
| id_access_token | string | An access token previously registered with the identity server. Servers can treat this as optional to distinguish between r0.5-compatible clients and this specification version. Required if an id_server is supplied. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| sid | string | Required. The session ID. Session IDs are opaque strings that must consist entirely of the characters [0-9a-zA-Z.=_-]. Their length must not exceed 255 characters and they must not be empty. |
| submit_url | string | An optional field containing a URL where the client must submit the validation token to, with identical parameters to the Identity Service API's POST /validate/email/submitToken endpoint (without the requirement for an access token). The homeserver must send this token to the user (if applicable), who should then be prompted to provide it to the client. If this field is not present, the client can assume that verification will happen without the client's involvement provided the homeserver advertises this specification version in the /versions response (ie: r0.5.0). |
Example request:
POST /_matrix/client/r0/register/msisdn/requestToken HTTP/1.1 Content-Type: application/json { "client_secret": "monkeys_are_GREAT", "country": "GB", "phone_number": "07700900001", "send_attempt": 1, "next_link": "https://example.org/congratulations.html", "id_server": "id.example.com", "id_access_token": "string" }
Responses:
Status code 200:
An SMS message has been sent to the specified phone number. Note that this may be an SMS message containing the validation token or it may be informing the user of an error.
Example
{ "sid": "123abc", "submit_url": "https://example.org/path/to/submitToken" }
Status code 400:
Part of the request was invalid. This may include one of the following error codes:
Example
{ "errcode": "M_THREEPID_IN_USE", "error": "The specified address is already in use" }
Status code 403:
The homeserver does not permit the address to be bound.
Example
{ "errcode": "M_THREEPID_DENIED", "error": "Third party identifier is not allowed" }
Changes the password for an account on this homeserver.
This API endpoint uses the User-Interactive Authentication API to ensure the user changing the password is actually the owner of the account.
An access token should be submitted to this endpoint if the client has an active session.
The homeserver may change the flows available depending on whether a valid access token is provided. The homeserver SHOULD NOT revoke the access token provided in the request, however all other access tokens for the user should be revoked if the request succeeds.
| Rate-limited: | Yes. |
|---|---|
| Requires auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| JSON body parameters | ||
| new_password | string | Required. The new password for the account. |
| auth | Authentication Data | Additional authentication information for the user-interactive authentication API. |
| Parameter | Type | Description |
|---|---|---|
| type | string | Required. The login type that the client is attempting to complete. |
| session | string | The value of the session key given by the homeserver. |
Example request:
POST /_matrix/client/r0/account/password HTTP/1.1 Content-Type: application/json { "new_password": "ihatebananas", "auth": { "type": "example.type.foo", "session": "xxxxx", "example_credential": "verypoorsharedsecret" } }
Responses:
Status code 200:
The password has been changed.
Example
{}
Status code 401:
The homeserver requires additional authentication information.
Example
{ "flows": [ { "stages": [ "example.type.foo" ] } ], "params": { "example.type.baz": { "example_key": "foobar" } }, "session": "xxxxxxyz", "completed": [ "example.type.foo" ] }
Status code 429:
This request was rate-limited.
Example
{ "errcode": "M_LIMIT_EXCEEDED", "error": "Too many requests", "retry_after_ms": 2000 }
The homeserver must check that the given email address is associated with an account on this homeserver. This API should be used to request validation tokens when authenticating for the /account/password endpoint.
This API's parameters and response are identical to that of the /register/email/requestToken endpoint, except that M_THREEPID_NOT_FOUND may be returned if no account matching the given email address could be found. The server may instead send an email to the given address prompting the user to create an account. M_THREEPID_IN_USE may not be returned.
The homeserver should validate the email itself, either by sending a validation email itself or by using a service it has control over.
| Rate-limited: | No. |
|---|---|
| Requires auth: | No. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| JSON body parameters | ||
| client_secret | string | Required. A unique string generated by the client, and used to identify the validation attempt. It must be a string consisting of the characters [0-9a-zA-Z.=_-]. Its length must not exceed 255 characters and it must not be empty. |
| string | Required. The email address to validate. | |
| send_attempt | integer | Required. The server will only send an email if the send_attempt is a number greater than the most recent one which it has seen, scoped to that email + client_secret pair. This is to avoid repeatedly sending the same email in the case of request retries between the POSTing user and the identity server. The client should increment this value if they desire a new email (e.g. a reminder) to be sent. If they do not, the server should respond with success but not resend the email. |
| next_link | string | Optional. When the validation is completed, the identity server will redirect the user to this URL. This option is ignored when submitting 3PID validation information through a POST request. |
| id_server | string | The hostname of the identity server to communicate with. May optionally include a port. This parameter is ignored when the homeserver handles 3PID verification. This parameter is deprected with a plan to be removed in a future specification version for /account/password and /register requests. |
| id_access_token | string | An access token previously registered with the identity server. Servers can treat this as optional to distinguish between r0.5-compatible clients and this specification version. Required if an id_server is supplied. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| sid | string | Required. The session ID. Session IDs are opaque strings that must consist entirely of the characters [0-9a-zA-Z.=_-]. Their length must not exceed 255 characters and they must not be empty. |
| submit_url | string | An optional field containing a URL where the client must submit the validation token to, with identical parameters to the Identity Service API's POST /validate/email/submitToken endpoint (without the requirement for an access token). The homeserver must send this token to the user (if applicable), who should then be prompted to provide it to the client. If this field is not present, the client can assume that verification will happen without the client's involvement provided the homeserver advertises this specification version in the /versions response (ie: r0.5.0). |
Example request:
POST /_matrix/client/r0/account/password/email/requestToken HTTP/1.1 Content-Type: application/json { "client_secret": "monkeys_are_GREAT", "email"<EMAIL_ADDRESS>"send_attempt": 1, "next_link": "https://example.org/congratulations.html", "id_server": "id.example.com", "id_access_token": "string" }
Responses:
Status code 200:
An email was sent to the given address.
Example
{ "sid": "123abc", "submit_url": "https://example.org/path/to/submitToken" }
Status code 400:
The referenced third party identifier is not recognised by the homeserver, or the request was invalid. The error code M_SERVER_NOT_TRUSTED can be returned if the server does not trust/support the identity server provided in the request.
Example
{ "errcode": "M_THREEPID_NOT_FOUND", "error": "Email not found" }
Status code 403:
The homeserver does not allow the third party identifier as a contact option.
Example
{ "errcode": "M_THREEPID_DENIED", "error": "Third party identifier is not allowed" }
The homeserver must check that the given phone number is associated with an account on this homeserver. This API should be used to request validation tokens when authenticating for the /account/password endpoint.
This API's parameters and response are identical to that of the /register/msisdn/requestToken endpoint, except that M_THREEPID_NOT_FOUND may be returned if no account matching the given phone number could be found. The server may instead send the SMS to the given phone number prompting the user to create an account. M_THREEPID_IN_USE may not be returned.
The homeserver should validate the phone number itself, either by sending a validation message itself or by using a service it has control over.
| Rate-limited: | No. |
|---|---|
| Requires auth: | No. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| JSON body parameters | ||
| client_secret | string | Required. A unique string generated by the client, and used to identify the validation attempt. It must be a string consisting of the characters [0-9a-zA-Z.=_-]. Its length must not exceed 255 characters and it must not be empty. |
| country | string | Required. The two-letter uppercase ISO-3166-1 alpha-2 country code that the number in phone_number should be parsed as if it were dialled from. |
| phone_number | string | Required. The phone number to validate. |
| send_attempt | integer | Required. The server will only send an SMS if the send_attempt is a number greater than the most recent one which it has seen, scoped to that country + phone_number + client_secret triple. This is to avoid repeatedly sending the same SMS in the case of request retries between the POSTing user and the identity server. The client should increment this value if they desire a new SMS (e.g. a reminder) to be sent. |
| next_link | string | Optional. When the validation is completed, the identity server will redirect the user to this URL. This option is ignored when submitting 3PID validation information through a POST request. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| sid | string | Required. The session ID. Session IDs are opaque strings that must consist entirely of the characters [0-9a-zA-Z.=_-]. Their length must not exceed 255 characters and they must not be empty. |
| submit_url | string | An optional field containing a URL where the client must submit the validation token to, with identical parameters to the Identity Service API's POST /validate/email/submitToken endpoint (without the requirement for an access token). The homeserver must send this token to the user (if applicable), who should then be prompted to provide it to the client. If this field is not present, the client can assume that verification will happen without the client's involvement provided the homeserver advertises this specification version in the /versions response (ie: r0.5.0). |
Example request:
POST /_matrix/client/r0/account/password/msisdn/requestToken HTTP/1.1 Content-Type: application/json { "client_secret": "monkeys_are_GREAT", "country": "GB", "phone_number": "07700900001", "send_attempt": 1 }
Responses:
Status code 200:
An SMS message was sent to the given phone number.
Example
{ "sid": "123abc", "submit_url": "https://example.org/path/to/submitToken" }
Status code 400:
The referenced third party identifier is not recognised by the homeserver, or the request was invalid. The error code M_SERVER_NOT_TRUSTED can be returned if the server does not trust/support the identity server provided in the request.
Example
{ "errcode": "M_THREEPID_NOT_FOUND", "error": "Phone number not found" }
Status code 403:
The homeserver does not allow the third party identifier as a contact option.
Example
{ "errcode": "M_THREEPID_DENIED", "error": "Third party identifier is not allowed" }
Deactivate the user's account, removing all ability for the user to login again.
This API endpoint uses the User-Interactive Authentication API.
An access token should be submitted to this endpoint if the client has an active session.
The homeserver may change the flows available depending on whether a valid access token is provided.
Unlike other endpoints, this endpoint does not take an id_access_token parameter because the homeserver is expected to sign the request to the identity server instead.
| Rate-limited: | Yes. |
|---|---|
| Requires auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| JSON body parameters | ||
| auth | Authentication Data | Additional authentication information for the user-interactive authentication API. |
| id_server | string | The identity server to unbind all of the user's 3PIDs from. If not provided, the homeserver MUST use the id_server that was originally use to bind each identifier. If the homeserver does not know which id_server that was, it must return an id_server_unbind_result of no-support. |
| Parameter | Type | Description |
|---|---|---|
| type | string | Required. The login type that the client is attempting to complete. |
| session | string | The value of the session key given by the homeserver. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| id_server_unbind_result | enum | Required. An indicator as to whether or not the homeserver was able to unbind the user's 3PIDs from the identity server(s). success indicates that all identifiers have been unbound from the identity server while no-support indicates that one or more identifiers failed to unbind due to the identity server refusing the request or the homeserver being unable to determine an identity server to unbind from. This must be success if the homeserver has no identifiers to unbind for the user. One of: ["success", "no-support"] |
Example request:
POST /_matrix/client/r0/account/deactivate HTTP/1.1 Content-Type: application/json { "auth": { "type": "example.type.foo", "session": "xxxxx", "example_credential": "verypoorsharedsecret" }, "id_server": "example.org" }
Responses:
Status code 200:
The account has been deactivated.
Example
{ "id_server_unbind_result": "success" }
Status code 401:
The homeserver requires additional authentication information.
Example
{ "flows": [ { "stages": [ "example.type.foo" ] } ], "params": { "example.type.baz": { "example_key": "foobar" } }, "session": "xxxxxxyz", "completed": [ "example.type.foo" ] }
Status code 429:
This request was rate-limited.
Example
{ "errcode": "M_LIMIT_EXCEEDED", "error": "Too many requests", "retry_after_ms": 2000 }
Checks to see if a username is available, and valid, for the server.
The server should check to ensure that, at the time of the request, the username requested is available for use. This includes verifying that an application service has not claimed the username and that the username fits the server's desired requirements (for example, a server could dictate that it does not permit usernames with underscores).
Matrix clients may wish to use this API prior to attempting registration, however the clients must also be aware that using this API does not normally reserve the username. This can mean that the username becomes unavailable between checking its availability and attempting to register it.
| Rate-limited: | Yes. |
|---|---|
| Requires auth: | No. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| query parameters | ||
| username | string | Required. The username to check the availability of. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| available | boolean | A flag to indicate that the username is available. This should always be true when the server replies with 200 OK. |
Example request:
GET /_matrix/client/r0/register/available?username=my_cool_localpart HTTP/1.1
Responses:
Status code 200:
The username is available
Example
{ "available": true }
Status code 400:
Part of the request was invalid or the username is not available. This may include one of the following error codes:
Example
{ "errcode": "M_USER_IN_USE", "error": "Desired user ID is already taken." }
Status code 429:
This request was rate-limited.
Example
{ "errcode": "M_LIMIT_EXCEEDED", "error": "Too many requests", "retry_after_ms": 2000 }
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.
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.
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 identifer can be added and bound at the same time, depending on context.
Gets a list of the third party identifiers that the homeserver has associated with the user's account.
This is not the same as the list of third party identifiers bound to the user's Matrix ID in identity servers.
Identifiers in this list may be used by the homeserver as, for example, identifiers that it will accept to reset the user's account password.
| Rate-limited: | No. |
|---|---|
| Requires auth: | Yes. |
Request format:
No parameters
Response format:
| Parameter | Type | Description |
|---|---|---|
| threepids | [Third party identifier] |
| Parameter | Type | Description |
|---|---|---|
| medium | enum | Required. The medium of the third party identifier. One of: ["email", "msisdn"] |
| address | string | Required. The third party identifier address. |
| validated_at | integer | Required. The timestamp, in milliseconds, when the identifier was validated by the identity server. |
| added_at | integer | Required. The timestamp, in milliseconds, when the homeserver associated the third party identifier with the user. |
Example request:
GET /_matrix/client/r0/account/3pid HTTP/1.1
Response:
Status code 200:
The lookup was successful.
Example
{ "threepids": [ { "medium": "email", "address"<EMAIL_ADDRESS>"validated_at":<PHONE_NUMBER>000, "added_at":<PHONE_NUMBER>756 } ] }
Warning
This API is deprecated and will be removed from a future release.
Adds contact information to the user's account.
This endpoint is deprecated in favour of the more specific /3pid/add and /3pid/bind endpoints.
Note
Previously this endpoint supported a bind parameter. This parameter has been removed, making this endpoint behave as though it was false. This results in this endpoint being an equivalent to /3pid/bind rather than dual-purpose.
| Rate-limited: | No. |
|---|---|
| Requires auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| JSON body parameters | ||
| three_pid_creds | ThreePidCredentials | Required. The third party credentials to associate with the account. |
| Parameter | Type | Description |
|---|---|---|
| client_secret | string | Required. The client secret used in the session with the identity server. |
| id_server | string | Required. The identity server to use. |
| id_access_token | string | Required. An access token previously registered with the identity server. Servers can treat this as optional to distinguish between r0.5-compatible clients and this specification version. |
| sid | string | Required. The session identifier given by the identity server. |
Example request:
POST /_matrix/client/r0/account/3pid HTTP/1.1 Content-Type: application/json { "three_pid_creds": { "id_server": "matrix.org", "id_access_token": "abc123_OpaqueString", "sid": "abc123987", "client_secret": "d0n'tT3ll" } }
Responses:
Status code 200:
The addition was successful.
Example
{ "submit_url": "https://example.org/path/to/submitToken" }
Status code 403:
The credentials could not be verified with the identity server.
Example
{ "errcode": "M_THREEPID_AUTH_FAILED", "error": "The third party credentials could not be verified by the identity server." }
This API endpoint uses the User-Interactive Authentication API.
Adds contact information to the user's account. Homeservers should use 3PIDs added through this endpoint for password resets instead of relying on the identity server.
Homeservers should prevent the caller from adding a 3PID to their account if it has already been added to another user's account on the homeserver.
| Rate-limited: | Yes. |
|---|---|
| Requires auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| JSON body parameters | ||
| auth | Authentication Data | Additional authentication information for the user-interactive authentication API. |
| client_secret | string | Required. The client secret used in the session with the homeserver. |
| sid | string | Required. The session identifier given by the homeserver. |
| Parameter | Type | Description |
|---|---|---|
| type | string | Required. The login type that the client is attempting to complete. |
| session | string | The value of the session key given by the homeserver. |
Example request:
POST /_matrix/client/r0/account/3pid/add HTTP/1.1 Content-Type: application/json { "sid": "abc123987", "client_secret": "d0n'tT3ll" }
Responses:
Status code 200:
The addition was successful.
Example
{}
Status code 401:
The homeserver requires additional authentication information.
Example
{ "flows": [ { "stages": [ "example.type.foo" ] } ], "params": { "example.type.baz": { "example_key": "foobar" } }, "session": "xxxxxxyz", "completed": [ "example.type.foo" ] }
Status code 429:
This request was rate-limited.
Example
{ "errcode": "M_LIMIT_EXCEEDED", "error": "Too many requests", "retry_after_ms": 2000 }
Binds a 3PID to the user's account through the specified identity server.
Homeservers should not prevent this request from succeeding if another user has bound the 3PID. Homeservers should simply proxy any errors received by the identity server to the caller.
Homeservers should track successful binds so they can be unbound later.
| Rate-limited: | Yes. |
|---|---|
| Requires auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| JSON body parameters | ||
| client_secret | string | Required. The client secret used in the session with the identity server. |
| id_server | string | Required. The identity server to use. |
| id_access_token | string | Required. An access token previously registered with the identity server. |
| sid | string | Required. The session identifier given by the identity server. |
Example request:
POST /_matrix/client/r0/account/3pid/bind HTTP/1.1 Content-Type: application/json { "id_server": "example.org", "id_access_token": "abc123_OpaqueString", "sid": "abc123987", "client_secret": "d0n'tT3ll" }
Responses:
Status code 200:
The addition was successful.
Example
{}
Status code 429:
This request was rate-limited.
Example
{ "errcode": "M_LIMIT_EXCEEDED", "error": "Too many requests", "retry_after_ms": 2000 }
Removes a third party identifier from the user's account. This might not cause an unbind of the identifier from the identity server.
Unlike other endpoints, this endpoint does not take an id_access_token parameter because the homeserver is expected to sign the request to the identity server instead.
| Rate-limited: | No. |
|---|---|
| Requires auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| JSON body parameters | ||
| id_server | string | The identity server to unbind from. If not provided, the homeserver MUST use the id_server the identifier was added through. If the homeserver does not know the original id_server, it MUST return a id_server_unbind_result of no-support. |
| medium | enum | Required. The medium of the third party identifier being removed. One of: ["email", "msisdn"] |
| address | string | Required. The third party address being removed. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| id_server_unbind_result | enum | Required. An indicator as to whether or not the homeserver was able to unbind the 3PID from the identity server. success indicates that the indentity server has unbound the identifier whereas no-support indicates that the identity server refuses to support the request or the homeserver was not able to determine an identity server to unbind from. One of: ["no-support", "success"] |
Example request:
POST /_matrix/client/r0/account/3pid/delete HTTP/1.1 Content-Type: application/json { "id_server": "example.org", "medium": "email", "address"<EMAIL_ADDRESS>}
Response:
Status code 200:
The homeserver has disassociated the third party identifier from the user.
Example
{ "id_server_unbind_result": "success" }
Removes a user's third party identifier from the provided identity server without removing it from the homeserver.
Unlike other endpoints, this endpoint does not take an id_access_token parameter because the homeserver is expected to sign the request to the identity server instead.
| Rate-limited: | No. |
|---|---|
| Requires auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| JSON body parameters | ||
| id_server | string | The identity server to unbind from. If not provided, the homeserver MUST use the id_server the identifier was added through. If the homeserver does not know the original id_server, it MUST return a id_server_unbind_result of no-support. |
| medium | enum | Required. The medium of the third party identifier being removed. One of: ["email", "msisdn"] |
| address | string | Required. The third party address being removed. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| id_server_unbind_result | enum | Required. An indicator as to whether or not the identity server was able to unbind the 3PID. success indicates that the identity server has unbound the identifier whereas no-support indicates that the identity server refuses to support the request or the homeserver was not able to determine an identity server to unbind from. One of: ["no-support", "success"] |
Example request:
POST /_matrix/client/r0/account/3pid/unbind HTTP/1.1 Content-Type: application/json { "id_server": "example.org", "medium": "email", "address"<EMAIL_ADDRESS>}
Response:
Status code 200:
The identity server has disassociated the third party identifier from the user.
Example
{ "id_server_unbind_result": "success" }
The homeserver must check that the given email address is not already associated with an account on this homeserver. This API should be used to request validation tokens when adding an email address to an account. This API's parameters and response are identical to that of the /register/email/requestToken endpoint. The homeserver should validate the email itself, either by sending a validation email itself or by using a service it has control over.
| Rate-limited: | No. |
|---|---|
| Requires auth: | No. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| JSON body parameters | ||
| client_secret | string | Required. A unique string generated by the client, and used to identify the validation attempt. It must be a string consisting of the characters [0-9a-zA-Z.=_-]. Its length must not exceed 255 characters and it must not be empty. |
| string | Required. The email address to validate. | |
| send_attempt | integer | Required. The server will only send an email if the send_attempt is a number greater than the most recent one which it has seen, scoped to that email + client_secret pair. This is to avoid repeatedly sending the same email in the case of request retries between the POSTing user and the identity server. The client should increment this value if they desire a new email (e.g. a reminder) to be sent. If they do not, the server should respond with success but not resend the email. |
| next_link | string | Optional. When the validation is completed, the identity server will redirect the user to this URL. This option is ignored when submitting 3PID validation information through a POST request. |
| id_server | string | The hostname of the identity server to communicate with. May optionally include a port. This parameter is ignored when the homeserver handles 3PID verification. This parameter is deprected with a plan to be removed in a future specification version for /account/password and /register requests. |
| id_access_token | string | An access token previously registered with the identity server. Servers can treat this as optional to distinguish between r0.5-compatible clients and this specification version. Required if an id_server is supplied. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| sid | string | Required. The session ID. Session IDs are opaque strings that must consist entirely of the characters [0-9a-zA-Z.=_-]. Their length must not exceed 255 characters and they must not be empty. |
| submit_url | string | An optional field containing a URL where the client must submit the validation token to, with identical parameters to the Identity Service API's POST /validate/email/submitToken endpoint (without the requirement for an access token). The homeserver must send this token to the user (if applicable), who should then be prompted to provide it to the client. If this field is not present, the client can assume that verification will happen without the client's involvement provided the homeserver advertises this specification version in the /versions response (ie: r0.5.0). |
Example request:
POST /_matrix/client/r0/account/3pid/email/requestToken HTTP/1.1 Content-Type: application/json { "client_secret": "monkeys_are_GREAT", "email"<EMAIL_ADDRESS>"send_attempt": 1, "next_link": "https://example.org/congratulations.html", "id_server": "id.example.com", "id_access_token": "string" }
Responses:
Status code 200:
An email was sent to the given address. Note that this may be an email containing the validation token or it may be informing the user of an error.
Example
{ "sid": "123abc", "submit_url": "https://example.org/path/to/submitToken" }
Status code 400:
The third party identifier is already in use on the homeserver, or the request was invalid. The error code M_SERVER_NOT_TRUSTED can be returned if the server does not trust/support the identity server provided in the request.
Example
{ "errcode": "M_THREEPID_IN_USE", "error": "Third party identifier already in use" }
Status code 403:
The homeserver does not allow the third party identifier as a contact option.
Example
{ "errcode": "M_THREEPID_DENIED", "error": "Third party identifier is not allowed" }
The homeserver must check that the given phone number is not already associated with an account on this homeserver. This API should be used to request validation tokens when adding a phone number to an account. This API's parameters and response are identical to that of the /register/msisdn/requestToken endpoint. The homeserver should validate the phone number itself, either by sending a validation message itself or by using a service it has control over.
| Rate-limited: | No. |
|---|---|
| Requires auth: | No. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| JSON body parameters | ||
| client_secret | string | Required. A unique string generated by the client, and used to identify the validation attempt. It must be a string consisting of the characters [0-9a-zA-Z.=_-]. Its length must not exceed 255 characters and it must not be empty. |
| country | string | Required. The two-letter uppercase ISO-3166-1 alpha-2 country code that the number in phone_number should be parsed as if it were dialled from. |
| phone_number | string | Required. The phone number to validate. |
| send_attempt | integer | Required. The server will only send an SMS if the send_attempt is a number greater than the most recent one which it has seen, scoped to that country + phone_number + client_secret triple. This is to avoid repeatedly sending the same SMS in the case of request retries between the POSTing user and the identity server. The client should increment this value if they desire a new SMS (e.g. a reminder) to be sent. |
| next_link | string | Optional. When the validation is completed, the identity server will redirect the user to this URL. This option is ignored when submitting 3PID validation information through a POST request. |
| id_server | string | The hostname of the identity server to communicate with. May optionally include a port. This parameter is ignored when the homeserver handles 3PID verification. This parameter is deprected with a plan to be removed in a future specification version for /account/password and /register requests. |
| id_access_token | string | An access token previously registered with the identity server. Servers can treat this as optional to distinguish between r0.5-compatible clients and this specification version. Required if an id_server is supplied. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| sid | string | Required. The session ID. Session IDs are opaque strings that must consist entirely of the characters [0-9a-zA-Z.=_-]. Their length must not exceed 255 characters and they must not be empty. |
| submit_url | string | An optional field containing a URL where the client must submit the validation token to, with identical parameters to the Identity Service API's POST /validate/email/submitToken endpoint (without the requirement for an access token). The homeserver must send this token to the user (if applicable), who should then be prompted to provide it to the client. If this field is not present, the client can assume that verification will happen without the client's involvement provided the homeserver advertises this specification version in the /versions response (ie: r0.5.0). |
Example request:
POST /_matrix/client/r0/account/3pid/msisdn/requestToken HTTP/1.1 Content-Type: application/json { "client_secret": "monkeys_are_GREAT", "country": "GB", "phone_number": "07700900001", "send_attempt": 1, "next_link": "https://example.org/congratulations.html", "id_server": "id.example.com", "id_access_token": "string" }
Responses:
Status code 200:
An SMS message was sent to the given phone number.
Example
{ "sid": "123abc", "submit_url": "https://example.org/path/to/submitToken" }
Status code 400:
The third party identifier is already in use on the homeserver, or the request was invalid. The error code M_SERVER_NOT_TRUSTED can be returned if the server does not trust/support the identity server provided in the request.
Example
{ "errcode": "M_THREEPID_IN_USE", "error": "Third party identifier already in use" }
Status code 403:
The homeserver does not allow the third party identifier as a contact option.
Example
{ "errcode": "M_THREEPID_DENIED", "error": "Third party identifier is not allowed" }
Gets information about the owner of a given access token.
Note that, as with the rest of the Client-Server API, Application Services may masquerade as users within their namespace by giving a user_id query parameter. In this situation, the server should verify that the given user_id is registered by the appservice, and return it in the response body.
| Rate-limited: | Yes. |
|---|---|
| Requires auth: | Yes. |
Request format:
No parameters
Response format:
| Parameter | Type | Description |
|---|---|---|
| user_id | string | Required. The user id that owns the access token. |
Example request:
GET /_matrix/client/r0/account/whoami HTTP/1.1
Responses:
Status code 200:
The token belongs to a known user.
Example
{ "user_id": "@joe:example.org" }
Status code 401:
The token is not recognised
Example
{ "errcode": "M_UNKNOWN_TOKEN", "error": "Unrecognised access token." }
Status code 403:
The appservice cannot masquerade as the user or has not registered them.
Example
{ "errcode": "M_FORBIDDEN", "error": "Application service has not registered this user." }
Status code 429:
This request was rate-limited.
Example
{ "errcode": "M_LIMIT_EXCEEDED", "error": "Too many requests", "retry_after_ms": 2000 }
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.
Persists the user's preferred identity server, or preference to not use an identity server at all, in the user's account data.
| Content Key | Type | Description |
|---|---|---|
| base_url | string | The URL of the identity server the user prefers to use, or null if the user does not want to use an identity server. This value is similar in structure to the base_url for identity servers in the .well-known/matrix/client schema. |
Example:
{ "content": { "base_url": "https://example.org" }, "type": "m.identity_server" }
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:
Some examples of what should not be a capability are:
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.
Gets information about the server's supported feature set and other relevant capabilities.
| Rate-limited: | Yes. |
|---|---|
| Requires auth: | Yes. |
Request format:
No parameters
Response format:
| Parameter | Type | Description |
|---|---|---|
| capabilities | Capabilities | Required. The custom capabilities the server supports, using the Java package naming convention. |
| Parameter | Type | Description |
|---|---|---|
| m.change_password | ChangePasswordCapability | Capability to indicate if the user can change their password. |
| m.room_versions | RoomVersionsCapability | The room versions the server supports. |
| Parameter | Type | Description |
|---|---|---|
| enabled | boolean | Required. True if the user can change their password, false otherwise. |
| Parameter | Type | Description |
|---|---|---|
| default | string | Required. The default room version the server is using for new rooms. |
| available | {string: RoomVersionStability} | Required. A detailed description of the room versions the server supports. |
| Parameter | Type | Description |
|---|---|---|
| (mapped value) | enum | The stability of the room version. One of: ["stable", "unstable"] |
Example request:
GET /_matrix/client/r0/capabilities HTTP/1.1
Responses:
Status code 200:
The capabilities of the server.
Example
{ "capabilities": { "m.change_password": { "enabled": false }, "m.room_versions": { "default": "1", "available": { "1": "stable", "2": "stable", "3": "unstable", "test-version": "unstable" } }, "com.example.custom.ratelimit": { "max_requests_per_hour": 600 } } }
Status code 429:
This request was rate-limited.
Example
{ "errcode": "M_LIMIT_EXCEEDED", "error": "Too many requests", "retry_after_ms": 2000 }
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 } } }
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.
Note
The paths referred to in this section are not actual endpoints. They only serve as examples to explain how pagination functions.
Pagination is the process of dividing a dataset into multiple discrete pages. Matrix makes use of pagination to allow clients to view extremely large datasets. These datasets are not limited to events in a room (for example clients may want to paginate a list of rooms in addition to events within those rooms). Regardless of what is being paginated, there is a common approach which is used to give clients an easy way of selecting subsets of a potentially changing dataset. Each endpoint that uses pagination may use different parameters. However the theme among them is that they take a from and to token, and occasionally a limit and dir. Together, these parameters describe the position in a data set, where from and to are known as "stream tokens" matching the regular expression [a-zA-Z0-9.=_-]+. If supported, the dir defines the direction of events to return: either forwards (f) or backwards (b). The response may contain tokens that can be used for retrieving results before or after the returned set. These tokens may be called start or prev_batch for retrieving the previous result set, or end, next_batch or next_token for retrieving the next result set.
In the following examples, 'START' and 'END' are placeholders to signify the start and end of the data sets respectively.
For example, if an endpoint had events E1 -> E15. The client wants the last 5 events and doesn't know any previous events:
S E |-E1-E2-E3-E4-E5-E6-E7-E8-E9-E10-E11-E12-E13-E14-E15-| | | | | _____| <--backwards-- | |__________________ | | ________| | | | | GET /somepath?to=START&limit=5&dir=b&from=END Returns: E15,E14,E13,E12,E11
Another example: a public room list has rooms R1 -> R17. The client is showing 5 rooms at a time on screen, and is on page 2. They want to now show page 3 (rooms R11 -> 15):
S E | 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | stream token |-R1-R2-R3-R4-R5-R6-R7-R8-R9-R10-R11-R12-R13-R14-R15-R16-R17| room |____________| |________________| | | Currently | viewing | | GET /roomslist?from=9&to=END&limit=5 Returns: R11,R12,R13,R14,R15
Note that tokens are treated in an exclusive, not inclusive, manner. The end token from the initial request was '9' which corresponded to R10. When the 2nd request was made, R10 did not appear again, even though from=9 was specified. If you know the token, you already have the data.
Responses for pagination-capable endpoints SHOULD have a chunk array alongside the applicable stream tokens to represent the result set.
In general, when the end of a result set is reached the applicable stream token will be excluded from the response. For example, if a user was backwards-paginating events in a room they'd eventually reach the first event in the room. In this scenario, the prev_batch token would be excluded from the response. Some paginated endpoints are open-ended in one direction, such as endpoints which expose an event stream for an active room. In this case, it is not possible for the client to reach the true "end" of the data set and therefore should always be presented with a token to keep moving forwards.
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.
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:
The current endpoints which support lazy-loading room members are:
Uploads a new filter definition to the homeserver. Returns a filter ID that may be used in future requests to restrict which events are returned to the client.
| Rate-limited: | No. |
|---|---|
| Requires auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| userId | string | Required. The id of the user uploading the filter. The access token must be authorized to make requests for this user id. |
| JSON body parameters | ||
| event_fields | [string] | List of event fields to include. If this list is absent then all fields are included. The entries may include '.' characters to indicate sub-fields. So ['content.body'] will include the 'body' field of the 'content' object. A literal '.' character in a field name may be escaped using a '\'. A server may include more fields than were requested. |
| event_format | enum | The format to use for events. 'client' will return the events in a format suitable for clients. 'federation' will return the raw event as received over federation. The default is 'client'. One of: ["client", "federation"] |
| presence | EventFilter | The presence updates to include. |
| account_data | EventFilter | The user account data that isn't associated with rooms to include. |
| room | RoomFilter | Filters to be applied to room data. |
| Parameter | Type | Description |
|---|---|---|
| limit | integer | The maximum number of events to return. |
| not_senders | [string] | A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the 'senders' filter. |
| not_types | [string] | A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the 'types' filter. A '*' can be used as a wildcard to match any sequence of characters. |
| senders | [string] | A list of senders IDs to include. If this list is absent then all senders are included. |
| types | [string] | A list of event types to include. If this list is absent then all event types are included. A '*' can be used as a wildcard to match any sequence of characters. |
| Parameter | Type | Description |
|---|---|---|
| not_rooms | [string] | A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the 'rooms' filter. This filter is applied before the filters in ephemeral, state, timeline or account_data |
| rooms | [string] | A list of room IDs to include. If this list is absent then all rooms are included. This filter is applied before the filters in ephemeral, state, timeline or account_data |
| ephemeral | RoomEventFilter | The events that aren't recorded in the room history, e.g. typing and receipts, to include for rooms. |
| include_leave | boolean | Include rooms that the user has left in the sync, default false |
| state | StateFilter | The state events to include for rooms. |
| timeline | RoomEventFilter | The message and state update events to include for rooms. |
| account_data | RoomEventFilter | The per user account data to include for rooms. |
| Parameter | Type | Description |
|---|---|---|
| limit | integer | The maximum number of events to return. |
| not_senders | [string] | A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the 'senders' filter. |
| not_types | [string] | A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the 'types' filter. A '*' can be used as a wildcard to match any sequence of characters. |
| senders | [string] | A list of senders IDs to include. If this list is absent then all senders are included. |
| types | [string] | A list of event types to include. If this list is absent then all event types are included. A '*' can be used as a wildcard to match any sequence of characters. |
| lazy_load_members | boolean | If true, enables lazy-loading of membership events. See Lazy-loading room members for more information. Defaults to false. |
| include_redundant_members | boolean | If true, sends all membership events for all events, even if they have already been sent to the client. Does not apply unless lazy_load_members is true. See Lazy- loading room members for more information. Defaults to false. |
| not_rooms | [string] | A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the 'rooms' filter. |
| rooms | [string] | A list of room IDs to include. If this list is absent then all rooms are included. |
| contains_url | boolean | If true, includes only events with a url key in their content. If false, excludes those events. If omitted, url key is not considered for filtering. |
| Parameter | Type | Description |
|---|---|---|
| limit | integer | The maximum number of events to return. |
| not_senders | [string] | A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the 'senders' filter. |
| not_types | [string] | A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the 'types' filter. A '*' can be used as a wildcard to match any sequence of characters. |
| senders | [string] | A list of senders IDs to include. If this list is absent then all senders are included. |
| types | [string] | A list of event types to include. If this list is absent then all event types are included. A '*' can be used as a wildcard to match any sequence of characters. |
| lazy_load_members | boolean | If true, enables lazy-loading of membership events. See Lazy-loading room members for more information. Defaults to false. |
| include_redundant_members | boolean | If true, sends all membership events for all events, even if they have already been sent to the client. Does not apply unless lazy_load_members is true. See Lazy- loading room members for more information. Defaults to false. |
| not_rooms | [string] | A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the 'rooms' filter. |
| rooms | [string] | A list of room IDs to include. If this list is absent then all rooms are included. |
| contains_url | boolean | If true, includes only events with a url key in their content. If false, excludes those events. If omitted, url key is not considered for filtering. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| filter_id | string | Required. The ID of the filter that was created. Cannot start with a { as this character is used to determine if the filter provided is inline JSON or a previously declared filter by homeservers on some APIs. |
Example request:
POST /_matrix/client/r0/user/%40alice%3Aexample.com/filter HTTP/1.1 Content-Type: application/json { "room": { "state": { "types": [ "m.room.*" ], "not_rooms": [ "!726s6s6q:example.com" ] }, "timeline": { "limit": 10, "types": [ "m.room.message" ], "not_rooms": [ "!726s6s6q:example.com" ], "not_senders": [ "@spam:example.com" ] }, "ephemeral": { "types": [ "m.receipt", "m.typing" ], "not_rooms": [ "!726s6s6q:example.com" ], "not_senders": [ "@spam:example.com" ] } }, "presence": { "types": [ "m.presence" ], "not_senders": [ "@alice:example.com" ] }, "event_format": "client", "event_fields": [ "type", "content", "sender" ] }
Response:
Status code 200:
The filter was created.
Example
{ "filter_id": "66696p746572" }
Download a filter
| Rate-limited: | No. |
|---|---|
| Requires auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| userId | string | Required. The user ID to download a filter for. |
| filterId | string | Required. The filter ID to download. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| event_fields | [string] | List of event fields to include. If this list is absent then all fields are included. The entries may include '.' characters to indicate sub-fields. So ['content.body'] will include the 'body' field of the 'content' object. A literal '.' character in a field name may be escaped using a '\'. A server may include more fields than were requested. |
| event_format | enum | The format to use for events. 'client' will return the events in a format suitable for clients. 'federation' will return the raw event as received over federation. The default is 'client'. One of: ["client", "federation"] |
| presence | EventFilter | The presence updates to include. |
| account_data | EventFilter | The user account data that isn't associated with rooms to include. |
| room | RoomFilter | Filters to be applied to room data. |
| Parameter | Type | Description |
|---|---|---|
| limit | integer | The maximum number of events to return. |
| not_senders | [string] | A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the 'senders' filter. |
| not_types | [string] | A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the 'types' filter. A '*' can be used as a wildcard to match any sequence of characters. |
| senders | [string] | A list of senders IDs to include. If this list is absent then all senders are included. |
| types | [string] | A list of event types to include. If this list is absent then all event types are included. A '*' can be used as a wildcard to match any sequence of characters. |
| Parameter | Type | Description |
|---|---|---|
| not_rooms | [string] | A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the 'rooms' filter. This filter is applied before the filters in ephemeral, state, timeline or account_data |
| rooms | [string] | A list of room IDs to include. If this list is absent then all rooms are included. This filter is applied before the filters in ephemeral, state, timeline or account_data |
| ephemeral | RoomEventFilter | The events that aren't recorded in the room history, e.g. typing and receipts, to include for rooms. |
| include_leave | boolean | Include rooms that the user has left in the sync, default false |
| state | StateFilter | The state events to include for rooms. |
| timeline | RoomEventFilter | The message and state update events to include for rooms. |
| account_data | RoomEventFilter | The per user account data to include for rooms. |
| Parameter | Type | Description |
|---|---|---|
| limit | integer | The maximum number of events to return. |
| not_senders | [string] | A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the 'senders' filter. |
| not_types | [string] | A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the 'types' filter. A '*' can be used as a wildcard to match any sequence of characters. |
| senders | [string] | A list of senders IDs to include. If this list is absent then all senders are included. |
| types | [string] | A list of event types to include. If this list is absent then all event types are included. A '*' can be used as a wildcard to match any sequence of characters. |
| lazy_load_members | boolean | If true, enables lazy-loading of membership events. See Lazy-loading room members for more information. Defaults to false. |
| include_redundant_members | boolean | If true, sends all membership events for all events, even if they have already been sent to the client. Does not apply unless lazy_load_members is true. See Lazy- loading room members for more information. Defaults to false. |
| not_rooms | [string] | A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the 'rooms' filter. |
| rooms | [string] | A list of room IDs to include. If this list is absent then all rooms are included. |
| contains_url | boolean | If true, includes only events with a url key in their content. If false, excludes those events. If omitted, url key is not considered for filtering. |
| Parameter | Type | Description |
|---|---|---|
| limit | integer | The maximum number of events to return. |
| not_senders | [string] | A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the 'senders' filter. |
| not_types | [string] | A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the 'types' filter. A '*' can be used as a wildcard to match any sequence of characters. |
| senders | [string] | A list of senders IDs to include. If this list is absent then all senders are included. |
| types | [string] | A list of event types to include. If this list is absent then all event types are included. A '*' can be used as a wildcard to match any sequence of characters. |
| lazy_load_members | boolean | If true, enables lazy-loading of membership events. See Lazy-loading room members for more information. Defaults to false. |
| include_redundant_members | boolean | If true, sends all membership events for all events, even if they have already been sent to the client. Does not apply unless lazy_load_members is true. See Lazy- loading room members for more information. Defaults to false. |
| not_rooms | [string] | A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the 'rooms' filter. |
| rooms | [string] | A list of room IDs to include. If this list is absent then all rooms are included. |
| contains_url | boolean | If true, includes only events with a url key in their content. If false, excludes those events. If omitted, url key is not considered for filtering. |
Example request:
GET /_matrix/client/r0/user/%40alice%3Aexample.com/filter/66696p746572 HTTP/1.1
Responses:
Status code 200:
"The filter defintion"
Example
{ "room": { "state": { "types": [ "m.room.*" ], "not_rooms": [ "!726s6s6q:example.com" ] }, "timeline": { "limit": 10, "types": [ "m.room.message" ], "not_rooms": [ "!726s6s6q:example.com" ], "not_senders": [ "@spam:example.com" ] }, "ephemeral": { "types": [ "m.receipt", "m.typing" ], "not_rooms": [ "!726s6s6q:example.com" ], "not_senders": [ "@spam:example.com" ] } }, "presence": { "types": [ "m.presence" ], "not_senders": [ "@alice:example.com" ] }, "event_format": "client", "event_fields": [ "type", "content", "sender" ] }
Status code 404:
Unknown filter.
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]
Warning
The format of events can change depending on room version. Check the room version specification for specific details on what to expect for event formats. Examples contained within the client-server specification are expected to be compatible with all specified room versions, however some differences may still apply.
For this version of the specification, clients only need to worry about the event ID format being different depending on room version. Clients should not be parsing the event ID, and instead be treating it as an opaque string. No changes should be required to support the currently available room versions.
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.
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.
Note that the structure of these events may be different than those in the server-server API.
The basic set of fields all events must have.
| Key | Type | Description |
|---|---|---|
| content | object | Required. The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body. |
| type | string | Required. The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type' |
Room Events have the following fields.
| Key | Type | Description |
|---|---|---|
| content | object | Required. The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body. |
| type | string | Required. The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type' |
| event_id | string | Required. The globally unique event identifier. |
| sender | string | Required. Contains the fully-qualified ID of the user who sent this event. |
| origin_server_ts | integer | Required. Timestamp in milliseconds on originating homeserver when this event was sent. |
| unsigned | UnsignedData | Contains optional extra information about the event. |
| room_id | string | Required. The ID of the room associated with this event. Will not be present on events that arrive through /sync, despite being required everywhere else. |
| Key | Type | Description |
|---|---|---|
| age | integer | The time in milliseconds that has elapsed since the event was sent. This field is generated by the local homeserver, and may be incorrect if the local time on at least one of the two servers is out of sync, which can cause the age to either be negative or greater than it actually is. |
| redacted_because | Event | Optional. The event that redacted this event, if any. |
| transaction_id | string | The client-supplied transaction ID, if the client being given the event is the same one which sent it. |
In addition to the fields of a Room Event, State Events have the following fields.
| Key | Type | Description |
|---|---|---|
| state_key | string | Required. A unique key which defines the overwriting semantics for this piece of room state. This value is often a zero-length string. The presence of this key makes this event a State Event. State keys starting with an @ are reserved for referencing user IDs, such as room members. With the exception of a few events, state events set with a given user's ID as the state key MUST only be set by that user. |
| prev_content | EventContent | Optional. The previous content for this event. If there is no previous content, this key will be missing. |
The complete event MUST NOT be larger than 65535 bytes, when formatted as a PDU for the Server-Server protocol, including any signatures, and encoded as Canonical JSON.
There are additional restrictions on sizes per key:
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 65 KB limit on events.
Note
This section is a work in progress.
This specification outlines several standard event types, all of which are prefixed with m.
This event is sent by a homeserver directly to inform of changes to the list of aliases it knows about for that room. The state_key for this event is set to the homeserver which owns the room alias. The entire set of known aliases for the room is the union of all the m.room.aliases events, one for each homeserver. Clients should check the validity of any room alias given in this list before presenting it to the user as trusted fact. The lists given by this event should be considered simply as advice on which aliases might exist, for which the client can perform the lookup to confirm whether it receives the correct room ID.
| Content Key | Type | Description |
|---|---|---|
| aliases | [string] | Required. A list of room aliases. |
Example:
{ "content": { "aliases": [ "#somewhere:example.org", "#another:example.org" ] }, "event_id": "$143273582443PhrSn:example.org", "origin_server_ts":<PHONE_NUMBER>653, "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@example:example.org", "state_key": "example.org", "type": "m.room.aliases", "unsigned": { "age": 1234 } }
This event is used to inform the room about which alias should be considered the canonical one. This could be for display purposes or as suggestion to users which alias to use to advertise the room.
A room with an m.room.canonical_alias event with an absent, null, or empty alias field should be treated the same as a room with no m.room.canonical_alias event.
| Content Key | Type | Description |
|---|---|---|
| alias | string | Required. The canonical alias. |
Example:
{ "content": { "alias": "#somewhere:localhost" }, "event_id": "$143273582443PhrSn:example.org", "origin_server_ts":<PHONE_NUMBER>653, "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@example:example.org", "state_key": "", "type": "m.room.canonical_alias", "unsigned": { "age": 1234 } }
This is the first event in a room and cannot be changed. It acts as the root of all other events.
| Content Key | Type | Description |
|---|---|---|
| creator | string | Required. The user_id of the room creator. This is set by the homeserver. |
| m.federate | boolean | Whether users on other servers can join this room. Defaults to true if key does not exist. |
| room_version | string | The version of the room. Defaults to "1" if the key does not exist. |
| predecessor | Previous Room | A reference to the room this room replaces, if the previous room was upgraded. |
| Previous Room Key | Type | Description |
|---|---|---|
| room_id | string | Required. The ID of the old room. |
| event_id | string | Required. The event ID of the last known event in the old room. |
Example:
{ "content": { "creator": "@example:example.org", "m.federate": true, "predecessor": { "event_id": "$something:example.org", "room_id": "!oldroom:example.org" }, "room_version": "1" }, "event_id": "$143273582443PhrSn:example.org", "origin_server_ts":<PHONE_NUMBER>653, "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@example:example.org", "state_key": "", "type": "m.room.create", "unsigned": { "age": 1234 } }
A room may be public meaning anyone can join the room without any prior action. Alternatively, it can be invite meaning that a user who wishes to join the room must first receive an invite to the room from someone already inside of the room. Currently, knock and private are reserved keywords which are not implemented.
| Content Key | Type | Description |
|---|---|---|
| join_rule | enum | Required. The type of rules used for users wishing to join this room. One of: ["public", "knock", "invite", "private"] |
Example:
{ "content": { "join_rule": "public" }, "event_id": "$143273582443PhrSn:example.org", "origin_server_ts":<PHONE_NUMBER>653, "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@example:example.org", "state_key": "", "type": "m.room.join_rules", "unsigned": { "age": 1234 } }
Adjusts the membership state for a user in a room. It is preferable to use the membership APIs (/rooms/<room id>/invite etc) when performing membership actions rather than adjusting the state directly as there are a restricted set of valid transformations. For example, user A cannot force user B to join a room, and trying to force this state change directly will fail.
The following membership states are specified:
The third_party_invite property will be set if this invite is an invite event and is the successor of an m.room.third_party_invite event, and absent otherwise.
This event may also include an invite_room_state key inside the event's unsigned data. If present, this contains an array of StrippedState Events. These events provide information on a subset of state events such as the room name.
The user for which a membership applies is represented by the state_key. Under some conditions, the sender and state_key may not match - this may be interpreted as the sender affecting the membership state of the state_key user.
The membership for a given user can change over time. The table below represents the various changes over time and how clients and servers must interpret those changes. Previous membership can be retrieved from the prev_content object on an event. If not present, the user's previous membership must be assumed as leave.
| to invite | to join | to leave | to ban | to knock | |
|---|---|---|---|---|---|
| from invite | No change. | User joined the room. | If the state_key is the same as the sender, the user rejected the invite. Otherwise, the state_key user had their invite revoked. | User was banned. | Not implemented. |
| from join | Must never happen. | displayname or avatar_url changed. | If the state_key is the same as the sender, the user left. Otherwise, the state_key user was kicked. | User was kicked and banned. | Not implemented. |
| from leave | New invitation sent. | User joined. | No change. | User was banned. | Not implemented. |
| from ban | Must never happen. | Must never happen. | User was unbanned. | No change. | Not implemented. |
| from knock | Not implemented. | Not implemented. | Not implemented. | Not implemented. | Not implemented. |
| EventContent Key | Type | Description |
|---|---|---|
| avatar_url | string | The avatar URL for this user, if any. This is added by the homeserver. |
| displayname | string or null | The display name for this user, if any. This is added by the homeserver. |
| membership | enum | Required. The membership state of the user. One of: ["invite", "join", "knock", "leave", "ban"] |
| is_direct | boolean | Flag indicating if the room containing this event was created with the intention of being a direct chat. See Direct Messaging. |
| third_party_invite | Invite | |
| unsigned | UnsignedData | Contains optional extra information about the event. |
| Invite Key | Type | Description |
|---|---|---|
| display_name | string | Required. A name which can be displayed to represent the user instead of their third party identifier |
| signed | signed | Required. A block of content which has been signed, which servers can use to verify the event. Clients should ignore this. |
| signed Key | Type | Description |
|---|---|---|
| mxid | string | Required. The invited matrix user ID. Must be equal to the user_id property of the event. |
| signatures | Signatures | Required. A single signature from the verifying server, in the format specified by the Signing Events section of the server-server API. |
| token | string | Required. The token property of the containing third_party_invite object. |
| UnsignedData Key | Type | Description |
|---|---|---|