4.1.1   GET /.well-known/matrix/client

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.

Request format:

No parameters

Response format:

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.

5.4.1   Overview

Some API endpoints require authentication that interacts with the user. The homeserver may provide many different ways of authenticating, such as user/password auth, login via a 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.

5.4.2   User-interactive API in the REST API

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

A client should first make a request with no auth parameter [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:

params

This section contains any information that the client will need to know in order to use a given type of authentication. For each authentication type presented, that type may be present as a key in this dictionary. For example, the public part of an OAuth client ID could be given here.

session

This is a session identifier that the client must pass back to the homeserver, if one is provided, in subsequent attempts to authenticate in the same API call.

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

POST /_matrix/client/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.

5.4.3   Example

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

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

5.4.4   Authentication types

This specification defines the following auth types:

• m.login.password
• m.login.recaptcha
• m.login.oauth2
• m.login.sso
• m.login.email.identity
• m.login.msisdn
• m.login.token
• m.login.dummy

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

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

{
  "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>"
}

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

{
  "type": "m.login.token",
  "token": "<token>",
  "txn_id": "<client generated nonce>",
  "session": "<session ID>"
}

{
  "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>"
}

{
  "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>"
}

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

5.4.5   Fallback

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

/_matrix/client/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>"
}

/**
 * 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);
}

5.4.6   Identifier types

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

This specification defines the following identifier types:

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

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

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

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

5.5.1   GET /_matrix/client/r0/login

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.

Request format:

No parameters

Response format:

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
}

5.5.2   POST /_matrix/client/r0/login

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.

Request format:

Response format:

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:

The login attempt failed. This can include one of the following error codes:

• M_FORBIDDEN: The provided authentication data was incorrect.
• M_USER_DEACTIVATED: The user has been deactivated.

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
}

5.5.3   POST /_matrix/client/r0/logout

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.

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

{}

5.5.4   POST /_matrix/client/r0/logout/all

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.

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

{}

5.5.5   Login Fallback

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.

5.6.1   POST /_matrix/client/r0/register

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:

• user accounts. These accounts may use the full API described in this specification.
• guest accounts. These accounts may have limited permissions and may not be supported by all servers.

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.

Request format:

Response format:

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:

• M_USER_IN_USE : The desired user ID is already taken.
• M_INVALID_USERNAME : The desired user ID is not a valid user name.
• M_EXCLUSIVE : The desired user ID is in the exclusive namespace claimed by an application service.

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
}

5.6.2   POST /_matrix/client/r0/register/email/requestToken

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.

Request format:

Response format:

Example request:

POST /_matrix/client/r0/register/email/requestToken HTTP/1.1
Content-Type: application/json

{
  "client_secret": "monkeys_are_GREAT",
  "email": "alice@example.org",
  "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:

• M_THREEPID_IN_USE : The email address is already registered to an account on this server. However, if the homeserver has the ability to send email, it is recommended that the server instead send an email to the user with instructions on how to reset their password. This prevents malicious parties from being able to determine if a given email address has an account on the homeserver in question.
• M_SERVER_NOT_TRUSTED : The id_server parameter refers to an identity server that is not trusted by this homeserver.

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"
}

5.6.3   POST /_matrix/client/r0/register/msisdn/requestToken

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.

Request format:

Response format:

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:

• M_THREEPID_IN_USE : The phone number is already registered to an account on this server. However, if the homeserver has the ability to send SMS message, it is recommended that the server instead send an SMS message to the user with instructions on how to reset their password. This prevents malicious parties from being able to determine if a given phone number has an account on the homeserver in question.
• M_SERVER_NOT_TRUSTED : The id_server parameter refers to an identity server that is not trusted by this homeserver.

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"
}

5.6.4   POST /_matrix/client/r0/account/password

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. Whether other access tokens for the user are revoked depends on the request parameters.

Request format:

Example request:

POST /_matrix/client/r0/account/password HTTP/1.1
Content-Type: application/json

{
  "new_password": "ihatebananas",
  "logout_devices": true,
  "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
}

5.6.5   POST /_matrix/client/r0/account/password/email/requestToken

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.

Request format:

Response format:

Example request:

POST /_matrix/client/r0/account/password/email/requestToken HTTP/1.1
Content-Type: application/json

{
  "client_secret": "monkeys_are_GREAT",
  "email": "alice@example.org",
  "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"
}

5.6.6   POST /_matrix/client/r0/account/password/msisdn/requestToken

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.

Request format:

Response format:

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"
}

5.6.7   POST /_matrix/client/r0/account/deactivate

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.

Request format:

Response format:

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
}

5.6.8   GET /_matrix/client/r0/register/available

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.

Request format:

Response format:

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:

• M_USER_IN_USE : The desired username is already taken.
• M_INVALID_USERNAME : The desired username is not a valid user name.
• M_EXCLUSIVE : The desired username is in the exclusive namespace claimed by an application service.

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
}

5.6.9   Notes on password management

5.7.1   GET /_matrix/client/r0/account/3pid

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.

Request format:

No parameters

Response format:

Example request:

GET /_matrix/client/r0/account/3pid HTTP/1.1

Response:

Status code 200:

The lookup was successful.

Example

{
  "threepids": [
    {
      "medium": "email",
      "address": "monkey@banana.island",
      "validated_at": 1535176800000,
      "added_at": 1535336848756
    }
  ]
}

5.7.2   Deprecated: POST /_matrix/client/r0/account/3pid

Adds contact information to the user's account.

This endpoint is deprecated in favour of the more specific /3pid/add and /3pid/bind endpoints.

Request format:

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."
}

5.7.3   POST /_matrix/client/r0/account/3pid/add

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.

Request format:

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
}

5.7.4   POST /_matrix/client/r0/account/3pid/bind

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.

Request format:

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
}

5.7.5   POST /_matrix/client/r0/account/3pid/delete

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.

Request format:

Response format:

Example request:

POST /_matrix/client/r0/account/3pid/delete HTTP/1.1
Content-Type: application/json

{
  "id_server": "example.org",
  "medium": "email",
  "address": "example@example.org"
}

Response:

Status code 200:

The homeserver has disassociated the third party identifier from the user.

Example

{
  "id_server_unbind_result": "success"
}

5.7.6   POST /_matrix/client/r0/account/3pid/unbind

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.

Request format:

Response format:

Example request:

POST /_matrix/client/r0/account/3pid/unbind HTTP/1.1
Content-Type: application/json

{
  "id_server": "example.org",
  "medium": "email",
  "address": "example@example.org"
}

Response:

Status code 200:

The identity server has disassociated the third party identifier from the user.

Example

{
  "id_server_unbind_result": "success"
}

5.7.7   POST /_matrix/client/r0/account/3pid/email/requestToken

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.

Request format:

Response format:

Example request:

POST /_matrix/client/r0/account/3pid/email/requestToken HTTP/1.1
Content-Type: application/json

{
  "client_secret": "monkeys_are_GREAT",
  "email": "alice@example.org",
  "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"
}

5.7.8   POST /_matrix/client/r0/account/3pid/msisdn/requestToken

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.

Request format:

Response format:

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"
}

5.8.1   GET /_matrix/client/r0/account/whoami

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.

Request format:

No parameters

Response format:

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
}

5.8.2   Notes on identity servers

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

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

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

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

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

{
    "content": {
        "base_url": "https://example.org"
    },
    "type": "m.identity_server"
}

8.2.1   POST /_matrix/client/r0/user/{userId}/filter

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.

Request format:

Response format:

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"
}

8.2.2   GET /_matrix/client/r0/user/{userId}/filter/{filterId}

Download a filter

Request format:

Response format:

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.

9.1.1   Event Fields

The basic set of fields all events must have.

9.1.2   Room Event Fields

Room Events have the following fields.

9.1.3   State Event Fields

In addition to the fields of a Room Event, State Events have the following fields.

9.3.1   m.room.canonical_alias

State Event

state_key: A zero-length string.

This event is used to inform the room about which alias should be considered the canonical one, and which other aliases point to the room. This could be for display purposes or as suggestion to users which alias to use to advertise and access the room.

Example:

{
    "content": {
        "alias": "#somewhere:localhost",
        "alt_aliases": [
            "#somewhere:example.org",
            "#myroom:example.com"
        ]
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
    "sender": "@example:example.org",
    "state_key": "",
    "type": "m.room.canonical_alias",
    "unsigned": {
        "age": 1234
    }
}

9.3.2   m.room.create

State Event

state_key: A zero-length string.

This is the first event in a room and cannot be changed. It acts as the root of all other events.

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": 1432735824653,
    "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
    "sender": "@example:example.org",
    "state_key": "",
    "type": "m.room.create",
    "unsigned": {
        "age": 1234
    }
}

9.3.3   m.room.join_rules

State Event

state_key: A zero-length string.

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.

Example:

{
    "content": {
        "join_rule": "public"
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
    "sender": "@example:example.org",
    "state_key": "",
    "type": "m.room.join_rules",
    "unsigned": {
        "age": 1234
    }
}

9.3.4   m.room.member

State Event

state_key: The user_id this membership event relates to. In all cases except for when membership is join, the user ID sending the event does not need to match the user ID in the state_key, unlike other events. Regular authorisation rules still apply.

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:

• invite - The user has been invited to join a room, but has not yet joined it. They may not participate in the room until they join.
• join - The user has joined the room (possibly after accepting an invite), and may participate in it.
• leave - The user was once joined to the room, but has since left (possibly by choice, or possibly by being kicked).
• ban - The user has been banned from the room, and is no longer allowed to join it until they are un-banned from the room (by having their membership state set to a value other than ban).
• knock - This is a reserved word, which currently has no meaning.

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.

Examples:

{
    "content": {
        "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
        "displayname": "Alice Margatroid",
        "membership": "join"
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
    "sender": "@example:example.org",
    "state_key": "@alice:example.org",
    "type": "m.room.member",
    "unsigned": {
        "age": 1234
    }
}

{
    "content": {
        "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
        "displayname": "Alice Margatroid",
        "membership": "invite"
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
    "sender": "@example:example.org",
    "state_key": "@alice:example.org",
    "type": "m.room.member",
    "unsigned": {
        "age": 1234,
        "invite_room_state": [
            {
                "content": {
                    "name": "Example Room"
                },
                "sender": "@bob:example.org",
                "state_key": "",
                "type": "m.room.name"
            },
            {
                "content": {
                    "join_rule": "invite"
                },
                "sender": "@bob:example.org",
                "state_key": "",
                "type": "m.room.join_rules"
            }
        ]
    }
}

{
    "content": {
        "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
        "displayname": "Alice Margatroid",
        "membership": "invite",
        "third_party_invite": {
            "display_name": "alice",
            "signed": {
                "mxid": "@alice:example.org",
                "signatures": {
                    "magic.forest": {
                        "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
                    }
                },
                "token": "abc123"
            }
        }
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
    "sender": "@example:example.org",
    "state_key": "@alice:example.org",
    "type": "m.room.member",
    "unsigned": {
        "age": 1234
    }
}