Client-Server API

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

API Standards

The mandatory baseline for client-server communication in Matrix is exchanging JSON objects over HTTP APIs. More efficient transports may be specified in future as optional extensions.

HTTPS is recommended for communication. The use of plain HTTP is not recommended outside test environments.

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

All POST and PUT endpoints, with the exception of POST /_matrix/media/v3/upload and PUT /_matrix/media/v3/upload/{serverName}/{mediaId}, require the client to supply a request body containing a (potentially empty) JSON object. Clients should supply a Content-Type header of application/json for all requests with JSON bodies, but this is not required.

Similarly, all endpoints require the server to return a JSON object, with the exception of 200 responses to GET /_matrix/media/v3/download/{serverName}/{mediaId} and GET /_matrix/media/v3/thumbnail/{serverName}/{mediaId}. Servers must include a Content-Type header of application/json for all JSON responses.

All JSON data, in requests or responses, must be encoded using UTF-8.

See also Conventions for Matrix APIs in the Appendices for conventions which all Matrix APIs are expected to follow, and Web Browser Clients below for additional requirements for server responses.

Standard error response

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

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

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

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

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

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

Common error codes

These error codes can be returned by any API endpoint:

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

M_UNKNOWN_TOKEN The access or refresh token specified was not recognised.

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

M_MISSING_TOKEN No access token was specified for the request.

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

M_NOT_JSON Request did not contain valid JSON.

M_NOT_FOUND No resource was found for this request.

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

M_UNRECOGNIZED The server did not understand the request. This is expected to be returned with a 404 HTTP status code if the endpoint is not implemented or a 405 HTTP status code if the endpoint is implemented, but the incorrect HTTP method is used.

M_UNKNOWN An unknown error has occurred.

Other error codes

The following error codes are specific to certain endpoints.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

M_CAPTCHA_NEEDED A Captcha is required to complete the request.

M_CAPTCHA_INVALID The Captcha provided did not match what was expected.

M_MISSING_PARAM A required parameter was missing from the request.

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

M_TOO_LARGE The request or entity was too large.

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

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

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

Rate limiting

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

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

Homeservers SHOULD include a Retry-After for any response with a 429 status code.

The retry_after_ms property MAY be included to tell the client how long they have to wait in milliseconds before they can try again. This property is deprecated, in favour of the Retry-After header.

[Changed in v1.10] : retry_after_ms property deprecated in favour of Retry-After header.

Transaction identifiers

The client-server API typically uses HTTP PUT to submit requests with a client-generated transaction identifier in the HTTP path.

The purpose of the transaction ID is to allow the homeserver to distinguish a new request from a retransmission of a previous request so that it can make the request idempotent.

The transaction ID should only be used for this purpose.

From the client perspective, after the request has finished, the {txnId} value should be changed by for the next request (how is not specified; a monotonically increasing integer is recommended).

The homeserver should identify a request as a retransmission if the transaction ID is the same as a previous request, and the path of the HTTP request is the same.

Where a retransmission has been identified, the homeserver should return the same HTTP response code and content as the original request. For example, PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId} would return a 200 OK with the event_id of the original request in the response body.

The scope of a transaction ID is for a single device, and a single HTTP endpoint. In other words: a single device could use the same transaction ID for a request to PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId} and PUT /_matrix/client/v3/sendToDevice/{eventType}/{txnId}, and the two requests would be considered distinct because the two are considered separate endpoints. Similarly, if a client logs out and back in between two requests using the same transaction ID, the requests are distinct because the act of logging in and out creates a new device (unless an existing device_id is passed to POST /_matrix/client/v3/login). On the other hand, if a client re-uses a transaction ID for the same endpoint after refreshing an access token, it will be assumed to be a duplicate request and ignored. See also Relationship between access tokens and devices.

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

Web Browser Clients

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

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

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

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

Server Discovery

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

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

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

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

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

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

Well-known URI

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

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

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

{
  "unstable_features": {
    "org.example.my_feature": true
  },
  "versions": [
    "r0.0.1",
    "v1.1"
  ]
}

{
  "contacts": [
    {
      "email_address": "[email protected]",
      "matrix_id": "@admin:example.org",
      "role": "m.role.admin"
    },
    {
      "email_address": "[email protected]",
      "role": "m.role.security"
    }
  ],
  "support_page": "https://example.org/support.html"
}

Client Authentication

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

Using access tokens

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

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

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

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

1. the access token was never valid.
2. the access token has been logged out.
3. the access token has been soft logged out.
4. [Added in v1.3] the access token needs to be refreshed.

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

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

Relationship between access tokens and devices

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

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

Refreshing access tokens

[Added in v1.3]

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

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

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

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

Soft logout

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

[Changed in v1.3]

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

User-Interactive Authentication API

Overview

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

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

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

User-interactive API in the REST API

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Example

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

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

Authentication types

This specification defines the following auth types:

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

Password-based

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

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

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

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

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

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

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

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

Google ReCaptcha

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

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

Single Sign-On

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

Email-based (identity / homeserver)

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

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

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

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

Phone number/MSISDN-based (identity / homeserver)

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

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

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

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

Dummy Auth

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

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

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

Token-authenticated registration

[Added in v1.2]

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

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

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

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

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

{
  "valid": true
}

{
  "errcode": "M_FORBIDDEN",
  "error": "Registration is not enabled on this homeserver."
}

{
  "errcode": "M_LIMIT_EXCEEDED",
  "error": "Too many requests",
  "retry_after_ms": 2000
}

Fallback

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

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

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

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

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

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

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

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

Example

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

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

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

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

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

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

    window.addEventListener("message", eventListener);

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

   popupWindow = window.open(url);
}

Identifier types

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

This specification defines the following identifier types:

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

Matrix User ID

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

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

Third-party ID

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

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

Phone number

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

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

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

Login

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

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

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

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

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

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

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

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

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

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

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

[Added in v1.7] Already-authenticated clients can additionally generate a token for their user ID if supported by the homeserver using POST /login/get_token.

{
  "flows": [
    {
      "type": "m.login.password"
    },
    {
      "get_login_token": true,
      "type": "m.login.token"
    }
  ]
}

{
  "errcode": "M_LIMIT_EXCEEDED",
  "error": "Too many requests",
  "retry_after_ms": 2000
}

{
  "identifier": {
    "type": "m.id.user",
    "user": "cheeky_monkey"
  },
  "initial_device_display_name": "Jungle Phone",
  "password": "ilovebananas",
  "type": "m.login.password"
}

{
  "access_token": "abc123",
  "device_id": "GHTYAJCE",
  "expires_in_ms": 60000,
  "refresh_token": "def456",
  "user_id": "@cheeky_monkey:matrix.org",
  "well_known": {
    "m.homeserver": {
      "base_url": "https://example.org"
    },
    "m.identity_server": {
      "base_url": "https://id.example.org"
    }
  }
}

{
  "errcode": "M_UNKNOWN",
  "error": "Bad login type."
}

{
  "errcode": "M_FORBIDDEN"
}

{
  "errcode": "M_LIMIT_EXCEEDED",
  "error": "Too many requests",
  "retry_after_ms": 2000
}

{
  "auth": {
    "example_credential": "verypoorsharedsecret",
    "session": "xxxxx",
    "type": "example.type.foo"
  }
}

{
  "expires_in_ms": 120000,
  "login_token": "<opaque string>"
}

{
  "errcode": "M_UNKNOWN",
  "error": "An unknown error occurred"
}

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

{
  "errcode": "M_LIMIT_EXCEEDED",
  "error": "Too many requests",
  "retry_after_ms": 2000
}

{
  "refresh_token": "some_token"
}

{
  "access_token": "a_new_token",
  "expires_in_ms": 60000,
  "refresh_token": "another_new_token"
}

{
  "errcode": "M_UNKNOWN_TOKEN",
  "error": "Soft logged out",
  "soft_logout": true
}

{
  "errcode": "M_LIMIT_EXCEEDED",
  "error": "Too many requests",
  "retry_after_ms": 2000
}

{}

{}

Appservice Login

[Added in v1.2]

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

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

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

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

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

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

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.

[Added in v1.1]

Non-credential parameters valid for the /login endpoint can be provided as query string parameters here. These are to be forwarded to the login endpoint during the login process. For example:

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

Account registration and management

{
  "auth": {
    "example_credential": "verypoorsharedsecret",
    "session": "xxxxx",
    "type": "example.type.foo"
  },
  "id_server": "example.org"
}

{
  "id_server_unbind_result": "success"
}

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

{
  "errcode": "M_LIMIT_EXCEEDED",
  "error": "Too many requests",
  "retry_after_ms": 2000
}

{
  "auth": {
    "example_credential": "verypoorsharedsecret",
    "session": "xxxxx",
    "type": "example.type.foo"
  },
  "logout_devices": true,
  "new_password": "ihatebananas"
}

{}

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

{
  "errcode": "M_LIMIT_EXCEEDED",
  "error": "Too many requests",
  "retry_after_ms": 2000
}

{
  "client_secret": "monkeys_are_GREAT",
  "email": "[email protected]",
  "id_server": "id.example.com",
  "next_link": "https://example.org/congratulations.html",
  "send_attempt": 1
}

{
  "sid": "123abc",
  "submit_url": "https://example.org/path/to/submitToken"
}

{
  "errcode": "M_THREEPID_NOT_FOUND",
  "error": "Email not found"
}

{
  "errcode": "M_THREEPID_DENIED",
  "error": "Third-party identifier is not allowed"
}

{
  "client_secret": "monkeys_are_GREAT",
  "country": "GB",
  "id_server": "id.example.com",
  "next_link": "https://example.org/congratulations.html",
  "phone_number": "07700900001",
  "send_attempt": 1
}

{
  "sid": "123abc",
  "submit_url": "https://example.org/path/to/submitToken"
}

{
  "errcode": "M_THREEPID_NOT_FOUND",
  "error": "Phone number not found"
}

{
  "errcode": "M_THREEPID_DENIED",
  "error": "Third-party identifier is not allowed"
}

{
  "auth": {
    "example_credential": "verypoorsharedsecret",
    "session": "xxxxx",
    "type": "example.type.foo"
  },
  "device_id": "GHTYAJCE",
  "initial_device_display_name": "Jungle Phone",
  "password": "ilovebananas",
  "username": "cheeky_monkey"
}

{
  "access_token": "abc123",
  "device_id": "GHTYAJCE",
  "user_id": "@cheeky_monkey:matrix.org"
}

{
  "errcode": "M_USER_IN_USE",
  "error": "Desired user ID is already taken."
}

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

{
  "errcode": "M_FORBIDDEN",
  "error": "Registration is disabled"
}

{
  "errcode": "M_LIMIT_EXCEEDED",
  "error": "Too many requests",
  "retry_after_ms": 2000
}

{
  "available": true
}

{
  "errcode": "M_USER_IN_USE",
  "error": "Desired user ID is already taken."
}

{
  "errcode": "M_LIMIT_EXCEEDED",
  "error": "Too many requests",
  "retry_after_ms": 2000
}

{
  "client_secret": "monkeys_are_GREAT",
  "email": "[email protected]",
  "id_server": "id.example.com",
  "next_link": "https://example.org/congratulations.html",
  "send_attempt": 1
}

{
  "sid": "123abc",
  "submit_url": "https://example.org/path/to/submitToken"
}

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

{
  "errcode": "M_THREEPID_DENIED",
  "error": "Third-party identifier is not allowed"
}

{
  "client_secret": "monkeys_are_GREAT",
  "country": "GB",
  "id_server": "id.example.com",
  "next_link": "https://example.org/congratulations.html",
  "phone_number": "07700900001",
  "send_attempt": 1
}

{
  "sid": "123abc",
  "submit_url": "https://example.org/path/to/submitToken"
}

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

{
  "errcode": "M_THREEPID_DENIED",
  "error": "Third-party identifier is not allowed"
}

Notes on password management

Adding Account Administrative Contact Information

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

{
  "threepids": [
    {
      "added_at": 1535336848756,
      "address": "[email protected]",
      "medium": "email",
      "validated_at": 1535176800000
    }
  ]
}

{
  "three_pid_creds": {
    "client_secret": "d0nt-T3ll",
    "id_access_token": "abc123_OpaqueString",
    "id_server": "matrix.org",
    "sid": "abc123987"
  }
}

{
  "submit_url": "https://example.org/path/to/submitToken"
}

{
  "errcode": "M_THREEPID_AUTH_FAILED",
  "error": "The third-party credentials could not be verified by the identity server."
}

{
  "auth": {
    "example_credential": "verypoorsharedsecret",
    "session": "xxxxx",
    "type": "example.type.foo"
  },
  "client_secret": "d0nt-T3ll",
  "sid": "abc123987"
}

{}

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

{
  "errcode": "M_LIMIT_EXCEEDED",
  "error": "Too many requests",
  "retry_after_ms": 2000
}

{
  "client_secret": "d0nt-T3ll",
  "id_access_token": "abc123_OpaqueString",
  "id_server": "example.org",
  "sid": "abc123987"
}

{}

{
  "errcode": "M_LIMIT_EXCEEDED",
  "error": "Too many requests",
  "retry_after_ms": 2000
}

{
  "address": "[email protected]",
  "id_server": "example.org",
  "medium": "email"
}

{
  "id_server_unbind_result": "success"
}

{
  "client_secret": "monkeys_are_GREAT",
  "email": "[email protected]",
  "id_server": "id.example.com",
  "next_link": "https://example.org/congratulations.html",
  "send_attempt": 1
}

{
  "sid": "123abc",
  "submit_url": "https://example.org/path/to/submitToken"
}

{
  "errcode": "M_THREEPID_IN_USE",
  "error": "Third-party identifier already in use"
}

{
  "errcode": "M_THREEPID_DENIED",
  "error": "Third-party identifier is not allowed"
}

{
  "client_secret": "monkeys_are_GREAT",
  "country": "GB",
  "id_server": "id.example.com",
  "next_link": "https://example.org/congratulations.html",
  "phone_number": "07700900001",
  "send_attempt": 1
}

{
  "sid": "123abc",
  "submit_url": "https://example.org/path/to/submitToken"
}

{
  "errcode": "M_THREEPID_IN_USE",
  "error": "Third-party identifier already in use"
}

{
  "errcode": "M_THREEPID_DENIED",
  "error": "Third-party identifier is not allowed"
}