3.2.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. When all stages in a flow are complete, authentication is complete and the API call succeeds.

3.2.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 home server, if one is provided, in subsequent attempts to authenticate in the same API call.

The client then chooses a flow and attempts to complete one of the stages. 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.

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.

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

3.2.4   Authentication types

This specification defines the following auth types:

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

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

{
  "type": "m.login.password",
  "medium": "<The medium of the third party identifier. Must be 'email'>",
  "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'>"
    }
  ],
  "session": "<session ID>"
}

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

3.2.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);
}

3.3.1   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",
  "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",
  "home_server": "matrix.org",
  "device_id": "GHTYAJCE"
}

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. For example, the password may have been incorrect.

Example

{
  "errcode": "M_FORBIDDEN"
}

Status code 429:

This request was rate-limited.

Example

{
  "errcode": "string",
  "error": "string"
}

3.3.2   POST /_matrix/client/r0/logout

Invalidates an existing access token, so that it can no longer be used for authorization.

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

{}

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

3.4.1   POST /_matrix/client/r0/register

This API endpoint uses the User-Interactive Authentication API.

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.

Request format:

Authentication Data

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"
  },
  "bind_email": false,
  "username": "cheeky_monkey",
  "password": "ilovebananas",
  "device_id": "GHTYAJCE",
  "initial_device_display_name": "Jungle Phone"
}

Responses:

Status code 200:

The account has been registered.

Example

{
  "user_id": "@cheeky_monkey:matrix.org",
  "access_token": "abc123",
  "home_server": "matrix.org",
  "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 429:

This request was rate-limited.

Example

{
  "errcode": "string",
  "error": "string"
}

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

Proxies the identity server API validate/email/requestToken, but first checks that the given email address is not already associated with an account on this Home Server. Note that, for consistency, this API takes JSON objects, though the Identity Server API takes x-www-form-urlencoded parameters. See the Identity Server API for further information.

Request format:

Example request:

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

{
  "id_server": "id.matrix.org",
  "client_secret": "this_is_my_secret_string",
  "email": "example@example.com",
  "send_attempt": "1"
}

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

{}

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 home server 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 Home Server in question.
• M_SERVER_NOT_TRUSTED : The id_server parameter refers to an ID server that is not trusted by this Home Server.

Example

{
  "errcode": "M_THREEPID_IN_USE",
  "error": "The specified address is already in use"
}

3.4.3   POST /_matrix/client/r0/account/password

Changes the password for an account on this homeserver.

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.

Request format:

Authentication Data

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": "string",
  "error": "string"
}

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

Proxies the identity server API validate/email/requestToken, but first checks that the given email address is associated with an account on this Home Server. 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 HS API /register/email/requestToken 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.

Request format:

No parameters

Example request:

POST /_matrix/client/r0/account/password/email/requestToken HTTP/1.1

Response:

Status code 200:

An email was sent to the given address

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

Request format:

Authentication Data

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

Responses:

Status code 200:

The account has been deactivated.

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": "string",
  "error": "string"
}

3.4.6   Notes on password management

3.5.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:

Third party identifier

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

3.5.2   POST /_matrix/client/r0/account/3pid

Adds contact information to the user's account.

Request format:

ThreePidCredentials

Example request:

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

{
  "three_pid_creds": {
    "id_server": "matrix.org",
    "sid": "abc123987",
    "client_secret": "d0n'tT3ll"
  },
  "bind": false
}

Responses:

Status code 200:

The addition was successful.

Example

{}

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

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

Proxies the identity server API validate/email/requestToken, but first checks that the given email address is not already associated with an account on this Home Server. This API should be used to request validation tokens when adding an email address to an account. This API's parameters and response is identical to that of the HS API /register/email/requestToken endpoint.

Request format:

No parameters

Example request:

POST /_matrix/client/r0/account/3pid/email/requestToken HTTP/1.1

Response:

Status code 200:

An email was sent to the given address

3.6.1   GET /_matrix/client/r0/account/whoami

Gets information about the owner of a given access token.

Request format:

No parameters

Response format:

Example request:

GET /_matrix/client/r0/account/whoami HTTP/1.1

Response:

Status code 200:

The token belongs to a known user.

Example

{
  "user_id": "@joe:example.org"
}

6.2.1   GET /_matrix/client/r0/sync

Synchronise the client's state with the latest state on the server. Clients use this API when they first log in to get an initial snapshot of the state on the server, and then continue to call this API to get incremental deltas to the state, and to receive new messages.

Request format:

Response format:

Rooms

Joined Room

Ephemeral

Unread Notification Counts

Invited Room

InviteState

Left Room

State

Timeline

Presence

Account Data

Event

Unsigned

Example request:

GET /_matrix/client/r0/sync?filter=66696p746572&since=s72594_4483_1934&full_state=false&set_presence=offline&timeout=30000 HTTP/1.1

Response:

Status code 200:

The initial snapshot or delta for the client to use to update their state.

Example

{
  "next_batch": "s72595_4483_1934",
  "presence": {
    "events": [
      {
        "sender": "@alice:example.com",
        "type": "m.presence",
        "content": {
          "presence": "online"
        }
      }
    ]
  },
  "account_data": {
    "events": [
      {
        "type": "org.example.custom.config",
        "content": {
          "custom_config_key": "custom_config_value"
        }
      }
    ]
  },
  "rooms": {
    "join": {
      "!726s6s6q:example.com": {
        "state": {
          "events": [
            {
              "sender": "@alice:example.com",
              "type": "m.room.member",
              "state_key": "@alice:example.com",
              "content": {
                "membership": "join"
              },
              "origin_server_ts": 1417731086795,
              "event_id": "$66697273743031:example.com"
            }
          ]
        },
        "timeline": {
          "events": [
            {
              "sender": "@bob:example.com",
              "type": "m.room.member",
              "state_key": "@bob:example.com",
              "content": {
                "membership": "join"
              },
              "prev_content": {
                "membership": "invite"
              },
              "origin_server_ts": 1417731086795,
              "event_id": "$7365636s6r6432:example.com"
            },
            {
              "sender": "@alice:example.com",
              "type": "m.room.message",
              "age": 124524,
              "txn_id": "1234",
              "content": {
                "body": "I am a fish",
                "msgtype": "m.text"
              },
              "origin_server_ts": 1417731086797,
              "event_id": "$74686972643033:example.com"
            }
          ],
          "limited": true,
          "prev_batch": "t34-23535_0_0"
        },
        "ephemeral": {
          "events": [
            {
              "type": "m.typing",
              "content": {
                "user_ids": [
                  "@alice:example.com"
                ]
              }
            }
          ]
        },
        "account_data": {
          "events": [
            {
              "type": "m.tag",
              "content": {
                "tags": {
                  "work": {
                    "order": 1
                  }
                }
              }
            },
            {
              "type": "org.example.custom.room.config",
              "content": {
                "custom_config_key": "custom_config_value"
              }
            }
          ]
        }
      }
    },
    "invite": {
      "!696r7674:example.com": {
        "invite_state": {
          "events": [
            {
              "sender": "@alice:example.com",
              "type": "m.room.name",
              "state_key": "",
              "content": {
                "name": "My Room Name"
              }
            },
            {
              "sender": "@alice:example.com",
              "type": "m.room.member",
              "state_key": "@bob:example.com",
              "content": {
                "membership": "invite"
              }
            }
          ]
        }
      }
    },
    "leave": {}
  }
}

6.2.2   GET /_matrix/client/r0/events

This will listen for new events and return them to the caller. This will block until an event is received, or until the timeout is reached.

This endpoint was deprecated in r0 of this specification. Clients should instead call the /sync API with a since parameter. See the migration guide.

Request format:

Response format:

Event

UnsignedData

Example request:

GET /_matrix/client/r0/events?from=s3456_9_0&timeout=35000 HTTP/1.1

Responses:

Status code 200:

The events received, which may be none.

Example

{
  "start": "s3456_9_0",
  "end": "s3457_9_0",
  "chunk": [
    {
      "age": 32,
      "content": {
        "body": "incoming message",
        "msgtype": "m.text"
      },
      "event_id": "$14328055551tzaee:localhost",
      "origin_server_ts": 1432804485886,
      "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
      "type": "m.room.message",
      "sender": "@bob:localhost"
    }
  ]
}

Status code 400:

Bad pagination from parameter.

6.2.3   GET /_matrix/client/r0/initialSync

This returns the full state for this user, with an optional limit on the number of messages per room to return.

This endpoint was deprecated in r0 of this specification. Clients should instead call the /sync API with no since parameter. See the migration guide.

Request format:

Response format:

RoomInfo

InviteEvent

EventContent

Invite

signed

StrippedState

PaginationChunk

RoomEvent

StateEvent

UnsignedData

Event

Example request:

GET /_matrix/client/r0/initialSync?limit=2&archived=true HTTP/1.1

Responses:

Status code 200:

The user's current state.

Example

{
  "end": "s3456_9_0",
  "presence": [
    {
      "content": {
        "avatar_url": "mxc://localhost/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
        "displayname": "Bob",
        "last_active_ago": 31053,
        "presence": "online",
        "user_id": "@bob:localhost"
      },
      "type": "m.presence"
    }
  ],
  "account_data": [
    {
      "type": "org.example.custom.config",
      "content": {
        "custom_config_key": "custom_config_value"
      }
    }
  ],
  "rooms": [
    {
      "membership": "join",
      "messages": {
        "chunk": [
          {
            "age": 343513403,
            "content": {
              "body": "foo",
              "msgtype": "m.text"
            },
            "event_id": "$14328044851tzTJS:localhost",
            "origin_server_ts": 1432804485886,
            "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
            "type": "m.room.message",
            "sender": "@alice:localhost"
          },
          {
            "age": 343511809,
            "content": {
              "body": "bar",
              "msgtype": "m.text"
            },
            "event_id": "$14328044872spjFg:localhost",
            "origin_server_ts": 1432804487480,
            "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
            "type": "m.room.message",
            "sender": "@bob:localhost"
          }
        ],
        "end": "s3456_9_0",
        "start": "t44-3453_9_0"
      },
      "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
      "state": [
        {
          "age": 7148266897,
          "content": {
            "join_rule": "public"
          },
          "event_id": "$14259997323TLwtb:localhost",
          "origin_server_ts": 1425999732392,
          "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
          "state_key": "",
          "type": "m.room.join_rules",
          "sender": "@alice:localhost"
        },
        {
          "age": 6547561012,
          "content": {
            "avatar_url": "mxc://localhost/fzysBrHpPEeTGANCVLXWXNMI#auto",
            "membership": "join"
          },
          "event_id": "$1426600438280zExKY:localhost",
          "membership": "join",
          "origin_server_ts": 1426600438277,
          "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
          "state_key": "@alice:localhost",
          "type": "m.room.member",
          "sender": "@alice:localhost"
        },
        {
          "age": 7148267200,
          "content": {
            "creator": "@alice:localhost"
          },
          "event_id": "$14259997320KhbwJ:localhost",
          "origin_server_ts": 1425999732089,
          "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
          "state_key": "",
          "type": "m.room.create",
          "sender": "@alice:localhost"
        },
        {
          "age": 1622568720,
          "content": {
            "avatar_url": "mxc://localhost/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
            "displayname": "Bob",
            "membership": "join"
          },
          "event_id": "$1431525430134MxlLX:localhost",
          "origin_server_ts": 1431525430569,
          "replaces_state": "$142652023736BSXcM:localhost",
          "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
          "state_key": "@bob:localhost",
          "type": "m.room.member",
          "sender": "@bob:localhost"
        },
        {
          "age": 7148267004,
          "content": {
            "ban": 50,
            "events": {
              "m.room.name": 100,
              "m.room.power_levels": 100
            },
            "events_default": 0,
            "kick": 50,
            "redact": 50,
            "state_default": 50,
            "users": {
              "@alice:localhost": 100
            },
            "users_default": 0
          },
          "event_id": "$14259997322mqfaq:localhost",
          "origin_server_ts": 1425999732285,
          "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
          "state_key": "",
          "type": "m.room.power_levels",
          "sender": "@alice:localhost"
        }
      ],
      "visibility": "private",
      "account_data": [
        {
          "type": "m.tag",
          "content": {
            "tags": {
              "work": {
                "order": 1
              }
            }
          }
        },
        {
          "type": "org.example.custom.room.config",
          "content": {
            "custom_config_key": "custom_config_value"
          }
        }
      ]
    }
  ]
}

Status code 404:

There is no avatar URL for this user or this user does not exist.

6.2.4   GET /_matrix/client/r0/events/{eventId}

Get a single event based on event_id. You must have permission to retrieve this event e.g. by being a member in the room for this event.

This endpoint was deprecated in r0 of this specification. Clients should instead call the /rooms/{roomId}/context/{eventId} API.

Request format:

Response format:

Event

Example request:

GET /_matrix/client/r0/events/%24asfDuShaf7Gafaw%3Amatrix.org HTTP/1.1

Responses:

Status code 200:

The full event.

Example

{
  "content": {
    "body": "Hello world!",
    "msgtype": "m.text"
  },
  "room_id": "!wfgy43Sg4a:matrix.org",
  "sender": "@bob:matrix.org",
  "event_id": "$asfDuShaf7Gafaw:matrix.org",
  "type": "m.room.message"
}

Status code 404:

The event was not found or you do not have permission to read this event.

6.3.1   GET /_matrix/client/r0/rooms/{roomId}/state/{eventType}/{stateKey}

Looks up the contents of a state event in a room. If the user is joined to the room then the state is taken from the current state of the room. If the user has left the room then the state is taken from the state of the room when they left.

Request format:

Example request:

GET /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/state/m.room.name/ HTTP/1.1

Responses:

Status code 200:

The content of the state event.

Example

{
  "name": "Example room name"
}

Status code 403:

You aren't a member of the room and weren't previously a member of the room.

Status code 404:

The room has no state with the given type or key.

6.3.2   GET /_matrix/client/r0/rooms/{roomId}/state/{eventType}

Looks up the contents of a state event in a room. If the user is joined to the room then the state is taken from the current state of the room. If the user has left the room then the state is taken from the state of the room when they left.

This looks up the state event with the empty state key.

Request format:

Example request:

GET /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/state/m.room.name HTTP/1.1

Responses:

Status code 200:

The content of the state event.

Example

{
  "name": "Example room name"
}

Status code 403:

You aren't a member of the room and weren't previously a member of the room.

Status code 404:

The room has no state with the given type or key.

6.3.3   GET /_matrix/client/r0/rooms/{roomId}/state

Get the state events for the current state of a room.

Request format:

Response format:

StateEvent

UnsignedData

Example request:

GET /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/state HTTP/1.1

Responses:

Status code 200:

The current state of the room

Example

[
  {
    "age": 7148266897,
    "content": {
      "join_rule": "public"
    },
    "event_id": "$14259997323TLwtb:example.com",
    "origin_server_ts": 1425999732392,
    "room_id": "!636q39766251:example.com",
    "state_key": "",
    "type": "m.room.join_rules",
    "sender": "@alice:example.com"
  },
  {
    "age": 6547561012,
    "content": {
      "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
      "membership": "join"
    },
    "event_id": "$1426600438280zExKY:example.com",
    "membership": "join",
    "origin_server_ts": 1426600438277,
    "room_id": "!636q39766251:example.com",
    "state_key": "@alice:example.com",
    "type": "m.room.member",
    "sender": "@alice:example.com"
  },
  {
    "age": 7148267200,
    "content": {
      "creator": "@alice:example.com"
    },
    "event_id": "$14259997320KhbwJ:example.com",
    "origin_server_ts": 1425999732089,
    "room_id": "!636q39766251:example.com",
    "state_key": "",
    "type": "m.room.create",
    "sender": "@alice:example.com"
  },
  {
    "age": 1622568720,
    "content": {
      "avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
      "displayname": "Bob",
      "membership": "join"
    },
    "event_id": "$1431525430134MxlLX:example.com",
    "origin_server_ts": 1431525430569,
    "replaces_state": "$142652023736BSXcM:example.com",
    "room_id": "!636q39766251:example.com",
    "state_key": "@bob:example.com",
    "type": "m.room.member",
    "sender": "@bob:example.com"
  },
  {
    "age": 7148267004,
    "content": {
      "ban": 50,
      "events": {
        "m.room.name": 100,
        "m.room.power_levels": 100
      },
      "events_default": 0,
      "kick": 50,
      "redact": 50,
      "state_default": 50,
      "users": {
        "@alice:example.com": 100
      },
      "users_default": 0
    },
    "event_id": "$14259997322mqfaq:example.com",
    "origin_server_ts": 1425999732285,
    "room_id": "!636q39766251:example.com",
    "state_key": "",
    "type": "m.room.power_levels",
    "sender": "@alice:example.com"
  }
]

Status code 403:

You aren't a member of the room and weren't previously a member of the room.

6.3.4   GET /_matrix/client/r0/rooms/{roomId}/members

Get the list of members for this room.

Request format:

Response format:

MemberEvent

EventContent

Invite

signed

UnsignedData

StrippedState

Example request:

GET /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/members HTTP/1.1

Responses:

Status code 200:

A list of members of the room. If you are joined to the room then this will be the current members of the room. If you have left the room then this will be the members of the room when you left.

Example

{
  "chunk": [
    {
      "age": 6547561012,
      "content": {
        "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
        "membership": "join"
      },
      "event_id": "$1426600438280zExKY:example.com",
      "membership": "join",
      "origin_server_ts": 1426600438277,
      "room_id": "!636q39766251:example.com",
      "state_key": "@alice:example.com",
      "type": "m.room.member",
      "sender": "@alice:example.com"
    },
    {
      "age": 1622568720,
      "content": {
        "avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
        "displayname": "Bob",
        "membership": "join"
      },
      "event_id": "$1431525430134MxlLX:example.com",
      "origin_server_ts": 1431525430569,
      "replaces_state": "$142652023736BSXcM:example.com",
      "room_id": "!636q39766251:example.com",
      "state_key": "@bob:example.com",
      "type": "m.room.member",
      "sender": "@bob:example.com"
    }
  ]
}

Status code 403:

You aren't a member of the room and weren't previously a member of the room.

6.3.5   GET /_matrix/client/r0/rooms/{roomId}/joined_members

This API returns a map of MXIDs to member info objects for members of the room. The current user must be in the room for it to work, unless it is an Application Service in which case any of the AS's users must be in the room. This API is primarily for Application Services and should be faster to respond than /members as it can be implemented more efficiently on the server.

Request format:

Response format:

RoomMember

Example request:

GET /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/joined_members HTTP/1.1

Responses:

Status code 200:

A map of MXID to room member objects.

Example

{
  "joined": {
    "@bar:example.com": {
      "display_name": "Bar",
      "avatar_url": "mxc://riot.ovh/printErCATzZijQsSDWorRaK"
    }
  }
}

Status code 403:

You aren't a member of the room.

6.3.6   GET /_matrix/client/r0/rooms/{roomId}/messages

This API returns a list of message and state events for a room. It uses pagination query parameters to paginate history in the room.

Request format:

Response format:

Example request:

GET /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/messages?from=s345_678_333&dir=b&limit=3&filter=%7B%22contains_url%22%3Atrue%7D HTTP/1.1

Responses:

Status code 200:

A list of messages with a new token to request more.

Example

{
  "start": "t47429-4392820_219380_26003_2265",
  "end": "t47409-4357353_219380_26003_2265",
  "chunk": [
    {
      "origin_server_ts": 1444812213737,
      "sender": "@alice:example.com",
      "event_id": "$1444812213350496Caaaa:example.com",
      "content": {
        "body": "hello world",
        "msgtype": "m.text"
      },
      "room_id": "!Xq3620DUiqCaoxq:example.com",
      "type": "m.room.message",
      "age": 1042
    },
    {
      "origin_server_ts": 1444812194656,
      "sender": "@bob:example.com",
      "event_id": "$1444812213350496Cbbbb:example.com",
      "content": {
        "body": "the world is big",
        "msgtype": "m.text"
      },
      "room_id": "!Xq3620DUiqCaoxq:example.com",
      "type": "m.room.message",
      "age": 20123
    },
    {
      "origin_server_ts": 1444812163990,
      "sender": "@bob:example.com",
      "event_id": "$1444812213350496Ccccc:example.com",
      "content": {
        "name": "New room name"
      },
      "prev_content": {
        "name": "Old room name"
      },
      "state_key": "",
      "room_id": "!Xq3620DUiqCaoxq:example.com",
      "type": "m.room.name",
      "age": 50789
    }
  ]
}

Status code 403:

You aren't a member of the room.

6.3.7   GET /_matrix/client/r0/rooms/{roomId}/initialSync

Get a copy of the current state and the most recent messages in a room.

This endpoint was deprecated in r0 of this specification. There is no direct replacement; the relevant information is returned by the /sync API. See the migration guide.

Request format:

Response format:

RoomInfo

PaginationChunk

RoomEvent

StateEvent

UnsignedData

Event

Example request:

GET /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/initialSync HTTP/1.1

Responses:

Status code 200:

The current state of the room

Example

{
  "membership": "join",
  "messages": {
    "chunk": [
      {
        "age": 343513403,
        "content": {
          "body": "foo",
          "msgtype": "m.text"
        },
        "event_id": "$14328044851tzTJS:example.com",
        "origin_server_ts": 1432804485886,
        "room_id": "!636q39766251:example.com",
        "type": "m.room.message",
        "sender": "@alice:example.com"
      },
      {
        "age": 343511809,
        "content": {
          "body": "bar",
          "msgtype": "m.text"
        },
        "event_id": "$14328044872spjFg:example.com",
        "origin_server_ts": 1432804487480,
        "room_id": "!636q39766251:example.com",
        "type": "m.room.message",
        "sender": "@bob:example.com"
      }
    ],
    "end": "s3456_9_0",
    "start": "t44-3453_9_0"
  },
  "room_id": "!636q39766251:example.com",
  "state": [
    {
      "age": 7148266897,
      "content": {
        "join_rule": "public"
      },
      "event_id": "$14259997323TLwtb:example.com",
      "origin_server_ts": 1425999732392,
      "room_id": "!636q39766251:example.com",
      "state_key": "",
      "type": "m.room.join_rules",
      "sender": "@alice:example.com"
    },
    {
      "age": 6547561012,
      "content": {
        "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
        "membership": "join"
      },
      "event_id": "$1426600438280zExKY:example.com",
      "membership": "join",
      "origin_server_ts": 1426600438277,
      "room_id": "!636q39766251:example.com",
      "state_key": "@alice:example.com",
      "type": "m.room.member",
      "sender": "@alice:example.com"
    },
    {
      "age": 7148267200,
      "content": {
        "creator": "@alice:example.com"
      },
      "event_id": "$14259997320KhbwJ:example.com",
      "origin_server_ts": 1425999732089,
      "room_id": "!636q39766251:example.com",
      "state_key": "",
      "type": "m.room.create",
      "sender": "@alice:example.com"
    },
    {
      "age": 1622568720,
      "content": {
        "avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
        "displayname": "Bob",
        "membership": "join"
      },
      "event_id": "$1431525430134MxlLX:example.com",
      "origin_server_ts": 1431525430569,
      "replaces_state": "$142652023736BSXcM:example.com",
      "room_id": "!636q39766251:example.com",
      "state_key": "@bob:example.com",
      "type": "m.room.member",
      "sender": "@bob:example.com"
    },
    {
      "age": 7148267004,
      "content": {
        "ban": 50,
        "events": {
          "m.room.name": 100,
          "m.room.power_levels": 100
        },
        "events_default": 0,
        "kick": 50,
        "redact": 50,
        "state_default": 50,
        "users": {
          "@alice:example.com": 100
        },
        "users_default": 0
      },
      "event_id": "$14259997322mqfaq:example.com",
      "origin_server_ts": 1425999732285,
      "room_id": "!636q39766251:example.com",
      "state_key": "",
      "type": "m.room.power_levels",
      "sender": "@alice:example.com"
    }
  ],
  "visibility": "private",
  "account_data": [
    {
      "type": "m.tag",
      "content": {
        "tags": {
          "work": {
            "order": "1"
          }
        }
      }
    }
  ]
}

Status code 403:

You aren't a member of the room and weren't previously a member of the room.

6.4.1   PUT /_matrix/client/r0/rooms/{roomId}/state/{eventType}/{stateKey}

State events can be sent using this endpoint. These events will be overwritten if <room id>, <event type> and <state key> all match.

Requests to this endpoint cannot use transaction IDs like other PUT paths because they cannot be differentiated from the state_key. Furthermore, POST is unsupported on state paths.

The body of the request should be the content object of the event; the fields in this object will vary depending on the type of event. See Room Events for the m. event specification.

Request format:

Response format:

Example request:

PUT /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/state/m.room.member/%40alice%3Aexample.com HTTP/1.1
Content-Type: application/json

{
  "membership": "join",
  "avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF#auto",
  "displayname": "Alice Margatroid"
}