Identity Service API

The Matrix client-server and server-server APIs are largely expressed in Matrix user identifiers. From time to time, it is useful to refer to users by other ("third-party") identifiers, or "3PID"s, e.g. their email address or phone number. This Identity Service Specification describes how mappings between third-party identifiers and Matrix user identifiers can be established, validated, and used. This description technically may apply to any 3PID, but in practice has only been applied specifically to email addresses and phone numbers.

Table of Contents

1   Changelog

Version: r0.3.0

New Endpoints

  • Add /account, /account/register, and /account/logout to authenticate with the identity server. (#2255)
  • Add endpoints for accepting and handling terms of service. (#2258)
  • Add /hash_details and a new /lookup endpoint for performing hashed association lookups. (#2287)

Backwards Compatible Changes

  • Deprecate the v1 API in favour of an authenticated v2 API. (#2254)

This version of the specification is generated from matrix-doc as of Git commit identity_service/release-r0.3.0,7351c0cd.

For the full historical changelog, see https://github.com/matrix-org/matrix-doc/blob/master/changelogs/identity_service.rst

1.1   Other versions of this specification

The following other versions are also available, in reverse chronological order:

2   General principles

The purpose of an identity server is to validate, store, and answer questions about the identities of users. In particular, it stores associations of the form "identifier X represents the same user as identifier Y", where identities may exist on different systems (such as email addresses, phone numbers, Matrix user IDs, etc).

The identity server has some private-public keypairs. When asked about an association, it will sign details of the association with its private key. Clients may validate the assertions about associations by verifying the signature with the public key of the identity server.

In general, identity servers are treated as reliable oracles. They do not necessarily provide evidence that they have validated associations, but claim to have done so. Establishing the trustworthiness of an individual identity server is left as an exercise for the client.

3PID types are described in 3PID Types Appendix.

3   API standards

The mandatory baseline for identity server communication in Matrix is exchanging JSON objects over HTTP APIs. HTTPS is required for communication, and all API calls use a Content-Type of application/json. In addition, strings MUST be encoded as UTF-8.

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. There may be additional keys depending on the error, but the keys error and errcode MUST always be present.

Some standard error codes are below:

M_NOT_FOUND:The resource requested could not be located.
M_MISSING_PARAMS:
 The request was missing one or more parameters.
M_INVALID_PARAM:
 The request contained one or more invalid parameters.
M_SESSION_NOT_VALIDATED:
 The session has not been validated.
M_NO_VALID_SESSION:
 A session could not be located for the given parameters.
M_SESSION_EXPIRED:
 The session has expired and must be renewed.
M_INVALID_EMAIL:
 The email address provided was not valid.
M_EMAIL_SEND_ERROR:
 There was an error sending an email. Typically seen when attempting to verify ownership of a given email address.
M_INVALID_ADDRESS:
 The provided third party address was not valid.
M_SEND_ERROR:There was an error sending a notification. Typically seen when attempting to verify ownership of a given third party address.
M_UNRECOGNIZED:The request contained an unrecognised value, such as an unknown token or medium.
M_THREEPID_IN_USE:
 The third party identifier is already in use by another user. Typically this error will have an additional mxid property to indicate who owns the third party identifier.
M_UNKNOWN:An unknown error has occurred.

4   Privacy

Identity is a privacy-sensitive issue. While the identity server exists to provide identity information, access should be restricted to avoid leaking potentially sensitive data. In particular, being able to construct large-scale connections between identities should be avoided. To this end, in general APIs should allow a 3PID to be mapped to a Matrix user identity, but not in the other direction (i.e. one should not be able to get all 3PIDs associated with a Matrix user ID, or get all 3PIDs associated with a 3PID).

5   Version 1 API deprecation

As described on each of the version 1 endpoints, the v1 API is deprecated in favour of the v2 API described here. The major difference, with the exception of a few isolated cases, is that the v2 API requires authentication to ensure the user has given permission for the identity server to operate on their data.

The v1 API is planned to be removed from the specification in a future version.

Clients SHOULD attempt the v2 endpoints first, and if they receive a 404, 400, or similar error they should try the v1 endpoint or fail the operation. Clients are strongly encouraged to warn the user of the risks in using the v1 API, if they are planning on using it.

6   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 identity server should respond to pre-flight requests and supply Cross-Origin Resource Sharing (CORS) headers on all requests.

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

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

7   Authentication

Most v2 endpoints in the Identity Service API require authentication in order to ensure that the requesting user has accepted all relevant policies and is otherwise permitted to make the request. The v1 API (currently deprecated) does not require this authentication, however using v1 is strongly discouraged as it will be removed in a future release.

Identity Servers use a scheme similar to the Client-Server API's concept of access tokens to authenticate users. The access tokens provided by an Identity Server cannot be used to authenticate Client-Server API requests.

An access token is provided to an endpoint in one of two ways:

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

Clients are encouraged to the 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_UNAUTHORIZED.

7.1   POST /_matrix/identity/v2/account/register

Exchanges an OpenID token from the homeserver for an access token to access the identity server. The request body is the same as the values returned by /openid/request_token in the Client-Server API.

Rate-limited:No.
Requires auth:No.

Request format:

Parameter Type Description
JSON body parameters
access_token string Required. An access token the consumer may use to verify the identity of the person who generated the token. This is given to the federation API GET /openid/userinfo to verify the user's identity.
token_type string Required. The string Bearer.
matrix_server_name string Required. The homeserver domain the consumer should use when attempting to verify the user's identity.
expires_in integer Required. The number of seconds before this token expires and a new one must be generated.

Response format:

Parameter Type Description
token string Required. An opaque string representing the token to authenticate future requests to the identity server with.

Example request:

POST /_matrix/identity/v2/account/register HTTP/1.1
Content-Type: application/json

{
  "access_token": "string",
  "token_type": "string",
  "matrix_server_name": "string",
  "expires_in": 0
}

Response:

Status code 200:

A token which can be used to authenticate future requests to the identity server.

Example

{
  "token": "abc123_OpaqueString"
}

7.2   GET /_matrix/identity/v2/account

Gets information about what user owns the access token used in the request.

Rate-limited:No.
Requires auth:Yes.

Request format:

No parameters

Response format:

Parameter Type Description
user_id string Required. The user ID which registered the token.

Example request:

GET /_matrix/identity/v2/account HTTP/1.1

Responses:

Status code 200:

The token holder's information.

Example

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

Status code 403:

The user must do something in order to use this endpoint. One example is an M_TERMS_NOT_SIGNED error where the user must agree to more terms.

Example

{
  "errcode": "M_TERMS_NOT_SIGNED",
  "error": "Please accept our updated terms of service before continuing"
}

7.3   POST /_matrix/identity/v2/account/logout

Logs out the access token, preventing it from being used to authenticate future requests to the server.

Rate-limited:No.
Requires auth:Yes.

Request format:

No parameters

Example request:

POST /_matrix/identity/v2/account/logout HTTP/1.1

Responses:

Status code 200:

The token was successfully logged out.

Example

{}

Status code 401:

The token is not registered or is otherwise unknown to the server.

Example

{
  "errcode": "M_UNKNOWN_TOKEN",
  "error": "Unrecognised access token"
}

Status code 403:

The user must do something in order to use this endpoint. One example is an M_TERMS_NOT_SIGNED error where the user must agree to more terms.

Example

{
  "errcode": "M_TERMS_NOT_SIGNED",
  "error": "Please accept our updated terms of service before continuing"
}

8   Terms of service

Identity Servers are encouraged to have terms of service (or similar policies) to ensure that users have agreed to their data being processed by the server. To facilitate this, an identity server can respond to almost any authenticated API endpoint with a HTTP 403 and the error code M_TERMS_NOT_SIGNED. The error code is used to indicate that the user must accept new terms of service before being able to continue.

All endpoints which support authentication can return the M_TERMS_NOT_SIGNED error. When clients receive the error, they are expected to make a call to GET /terms to find out what terms the server offers. The client compares this to the m.accepted_terms account data for the user (described later) and presents the user with option to accept the still-missing terms of service. After the user has made their selection, if applicable, the client sends a request to POST /terms to indicate the user's acceptance. The server cannot expect that the client will send acceptance for all pending terms, and the client should not expect that the server will not respond with another M_TERMS_NOT_SIGNED on their next request. The terms the user has just accepted are appended to m.accepted_terms.

8.1   m.accepted_terms

A list of terms URLs the user has previously accepted. Clients SHOULD use this to avoid presenting the user with terms they have already agreed to.

Content Key Type Description
accepted [string] The list of URLs the user has previously accepted. Should be appended to when the user agrees to new terms.

Example:

{
    "content": {
        "accepted": [
            "https://example.org/somewhere/terms-1.2-en.html",
            "https://example.org/somewhere/privacy-1.2-en.html"
        ]
    },
    "type": "m.accepted_terms"
}

8.2   GET /_matrix/identity/v2/terms

Gets all the terms of service offered by the server. The client is expected to filter through the terms to determine which terms need acceptance from the user. Note that this endpoint does not require authentication.

Rate-limited:No.
Requires auth:No.

Request format:

No parameters

Response format:

Parameter Type Description
policies {string: Policy Object} Required. The policies the server offers. Mapped from arbitrary ID (unused in this version of the specification) to a Policy Object.
Policy Object
Parameter Type Description
version string Required. The version for the policy. There are no requirements on what this might be and could be "alpha", semantically versioned, or arbitrary.

Example request:

GET /_matrix/identity/v2/terms HTTP/1.1

Response:

Status code 200:

The terms of service offered by the server.

Example

{
  "policies": {
    "terms_of_service": {
      "version": "2.0",
      "en": {
        "name": "Terms of Service",
        "url": "https://example.org/somewhere/terms-2.0-en.html"
      },
      "fr": {
        "name": "Conditions d'utilisation",
        "url": "https://example.org/somewhere/terms-2.0-fr.html"
      }
    },
    "privacy_policy": {
      "version": "1.2",
      "en": {
        "name": "Privacy Policy",
        "url": "https://example.org/somewhere/privacy-1.2-en.html"
      },
      "fr": {
        "name": "Politique de confidentialit\u00e9",
        "url": "https://example.org/somewhere/privacy-1.2-fr.html"
      }
    }
  }
}

8.3   POST /_matrix/identity/v2/terms

Called by a client to indicate that the user has accepted/agreed to the included set of URLs. Servers MUST NOT assume that the client will be sending all previously accepted URLs and should therefore append the provided URLs to what the server already knows has been accepted.

Clients MUST provide the URL of the policy in the language that was presented to the user. Servers SHOULD consider acceptance of any one language's URL as acceptance for all other languages of that policy.

The server should avoid returning M_TERMS_NOT_SIGNED because the client may not be accepting all terms at once.

Rate-limited:No.
Requires auth:Yes.

Request format:

Parameter Type Description
JSON body parameters
user_accepts [string] Required. The URLs the user is accepting in this request.

Example request:

POST /_matrix/identity/v2/terms HTTP/1.1
Content-Type: application/json

{
  "user_accepts": "https://example.org/somewhere/terms-2.0-en.html"
}

Response:

Status code 200:

The server has considered the user as having accepted the provided URLs.

Example

{}

9   Status check

9.1   Deprecated: GET /_matrix/identity/api/v1

Warning

This API is deprecated and will be removed from a future release.

Checks that an identity server is available at this API endpoint.

To discover that an identity server is available at a specific URL, this endpoint can be queried and will return an empty object.

This is primarly used for auto-discovery and health check purposes by entities acting as a client for the identity server.

Rate-limited:No.
Requires auth:No.

Request format:

No parameters

Example request:

GET /_matrix/identity/api/v1 HTTP/1.1

Response:

Status code 200:

An identity server is ready to serve requests.

Example

{}

9.2   GET /_matrix/identity/v2

Checks that an identity server is available at this API endpoint.

To discover that an identity server is available at a specific URL, this endpoint can be queried and will return an empty object.

This is primarly used for auto-discovery and health check purposes by entities acting as a client for the identity server.

Rate-limited:No.
Requires auth:No.

Request format:

No parameters

Example request:

GET /_matrix/identity/v2 HTTP/1.1

Response:

Status code 200:

An identity server is ready to serve requests.

Example

{}

10   Key management

An identity server has some long-term public-private keypairs. These are named in a scheme algorithm:identifier, e.g. ed25519:0. When signing an association, the standard Signing JSON algorithm applies.

The identity server may also keep track of some short-term public-private keypairs, which may have different usage and lifetime characteristics than the service's long-term keys.

10.1   Deprecated: GET /_matrix/identity/api/v1/pubkey/{keyId}

Warning

This API is deprecated and will be removed from a future release.

Get the public key for the passed key ID.

Rate-limited:No.
Requires auth:No.

Request format:

Parameter Type Description
path parameters
keyId string Required. The ID of the key. This should take the form algorithm:identifier where algorithm identifies the signing algorithm, and the identifier is an opaque string.

Response format:

Parameter Type Description
public_key string Required. Unpadded Base64 encoded public key.

Example request:

GET /_matrix/identity/api/v1/pubkey/ed25519%3A0 HTTP/1.1

Responses:

Status code 200:

The public key exists.

Example

{
  "public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
}

Status code 404:

The public key was not found.

Example

{
  "errcode": "M_NOT_FOUND",
  "error": "The public key was not found"
}

10.2   Deprecated: GET /_matrix/identity/api/v1/pubkey/isvalid

Warning

This API is deprecated and will be removed from a future release.

Check whether a long-term public key is valid. The response should always be the same, provided the key exists.

Rate-limited:No.
Requires auth:No.

Request format:

Parameter Type Description
query parameters
public_key string Required. The unpadded base64-encoded public key to check.

Response format:

Parameter Type Description
valid boolean Required. Whether the public key is recognised and is currently valid.

Example request:

GET /_matrix/identity/api/v1/pubkey/isvalid?public_key=VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c HTTP/1.1

Response:

Status code 200:

The validity of the public key.

Example

{
  "valid": true
}

10.3   Deprecated: GET /_matrix/identity/api/v1/pubkey/ephemeral/isvalid

Warning

This API is deprecated and will be removed from a future release.

Check whether a short-term public key is valid.

Rate-limited:No.
Requires auth:No.

Request format:

Parameter Type Description
query parameters
public_key string Required. The unpadded base64-encoded public key to check.

Response format:

Parameter Type Description
valid boolean Required. Whether the public key is recognised and is currently valid.

Example request:

GET /_matrix/identity/api/v1/pubkey/ephemeral/isvalid?public_key=VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c HTTP/1.1

Response:

Status code 200:

The validity of the public key.

Example

{
  "valid": true
}

10.4   GET /_matrix/identity/v2/pubkey/{keyId}

Get the public key for the passed key ID.

Rate-limited:No.
Requires auth:No.

Request format:

Parameter Type Description
path parameters
keyId string Required. The ID of the key. This should take the form algorithm:identifier where algorithm identifies the signing algorithm, and the identifier is an opaque string.

Response format:

Parameter Type Description
public_key string Required. Unpadded Base64 encoded public key.

Example request:

GET /_matrix/identity/v2/pubkey/ed25519%3A0 HTTP/1.1

Responses:

Status code 200:

The public key exists.

Example

{
  "public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
}

Status code 404:

The public key was not found.

Example

{
  "errcode": "M_NOT_FOUND",
  "error": "The public key was not found"
}

10.5   GET /_matrix/identity/v2/pubkey/isvalid

Check whether a long-term public key is valid. The response should always be the same, provided the key exists.

Rate-limited:No.
Requires auth:No.

Request format:

Parameter Type Description
query parameters
public_key string Required. The unpadded base64-encoded public key to check.

Response format:

Parameter Type Description
valid boolean Required. Whether the public key is recognised and is currently valid.

Example request:

GET /_matrix/identity/v2/pubkey/isvalid?public_key=VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c HTTP/1.1

Response:

Status code 200:

The validity of the public key.

Example

{
  "valid": true
}

10.6   GET /_matrix/identity/v2/pubkey/ephemeral/isvalid

Check whether a short-term public key is valid.

Rate-limited:No.
Requires auth:No.

Request format:

Parameter Type Description
query parameters
public_key string Required. The unpadded base64-encoded public key to check.

Response format:

Parameter Type Description
valid boolean Required. Whether the public key is recognised and is currently valid.

Example request:

GET /_matrix/identity/v2/pubkey/ephemeral/isvalid?public_key=VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c HTTP/1.1

Response:

Status code 200:

The validity of the public key.

Example

{
  "valid": true
}

11   Association lookup

11.1   Deprecated: GET /_matrix/identity/api/v1/lookup

Warning

This API is deprecated and will be removed from a future release.

Look up the Matrix user ID for a 3pid.

Rate-limited:No.
Requires auth:No.

Request format:

Parameter Type Description
query parameters
medium string Required. The medium type of the 3pid. See the 3PID Types Appendix.
address string Required. The address of the 3pid being looked up. See the 3PID Types Appendix.

Response format:

Parameter Type Description
address string Required. The 3pid address of the user being looked up, matching the address requested.
medium string Required. A medium from the 3PID Types Appendix, matching the medium requested.
mxid string Required. The Matrix user ID associated with the 3pid.
not_before integer Required. A unix timestamp before which the association is not known to be valid.
not_after integer Required. A unix timestamp after which the association is not known to be valid.
ts integer Required. The unix timestamp at which the association was verified.
signatures {string: {string: string}} Required. The signatures of the verifying identity servers which show that the association should be trusted, if you trust the verifying identity servers.

Example request:

GET /_matrix/identity/api/v1/lookup?medium=email&address=louise%40bobs.burgers HTTP/1.1

Response:

Status code 200:

The association for that 3pid, or an empty object if no association is known.

Example

{
  "address": "louise@bobs.burgers",
  "medium": "email",
  "mxid": "@ears:matrix.org",
  "not_before": 1428825849161,
  "not_after": 4582425849161,
  "ts": 1428825849161,
  "signatures": {
    "matrix.org": {
      "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
    }
  }
}

11.2   Deprecated: POST /_matrix/identity/api/v1/bulk_lookup

Warning

This API is deprecated and will be removed from a future release.

Lookup Matrix user IDs for a list of 3pids.

Rate-limited:No.
Requires auth:No.

Request format:

Parameter Type Description
JSON body parameters
threepids [[string, string]] Required. An array of arrays containing the 3PID Types with the medium in first position and the address in second position.

Response format:

Parameter Type Description
threepids [[string, string, string]] Required. An array of array containing the 3PID Types with the medium in first position, the address in second position and Matrix user ID in third position.

Example request:

POST /_matrix/identity/api/v1/bulk_lookup HTTP/1.1
Content-Type: application/json

{
  "threepids": [
    [
      "email",
      "user@example.org"
    ],
    [
      "msisdn",
      "123456789"
    ],
    [
      "email",
      "user2@example.org"
    ]
  ]
}

Response:

Status code 200:

A list of known 3PID mappings for the supplied 3PIDs.

Example

{
  "threepids": [
    [
      "email",
      "user@example.org",
      "@bla:example.org"
    ],
    [
      "msisdn",
      "123456789",
      "@blah2:example.com"
    ]
  ]
}

11.3   GET /_matrix/identity/v2/hash_details

Gets parameters for hashing identifiers from the server. This can include any of the algorithms defined in this specification.

Rate-limited:No.
Requires auth:Yes.

Request format:

No parameters

Response format:

Parameter Type Description
lookup_pepper string

Required. The pepper the client MUST use in hashing identifiers, and MUST supply to the /lookup endpoint when performing lookups.

Servers SHOULD rotate this string often.

algorithms [string] Required. The algorithms the server supports. Must contain at least sha256.

Example request:

GET /_matrix/identity/v2/hash_details HTTP/1.1

Response:

Status code 200:

The hash function information.

Example

{
  "lookup_pepper": "matrixrocks",
  "algorithms": [
    "none",
    "sha256"
  ]
}

11.4   POST /_matrix/identity/v2/lookup

Looks up the set of Matrix User IDs which have bound the 3PIDs given, if bindings are available. Note that the format of the addresses is defined later in this specification.

Rate-limited:No.
Requires auth:Yes.

Request format:

Parameter Type Description
JSON body parameters
algorithm string Required. The algorithm the client is using to encode the addresses. This should be one of the available options from /hash_details.
pepper string Required. The pepper from /hash_details. This is required even when the algorithm does not make use of it.
addresses [string] Required. The addresses to look up. The format of the entries here depend on the algorithm used. Note that queries which have been incorrectly hashed or formatted will lead to no matches.

Response format:

Parameter Type Description
mappings {string: string} Required. Any applicable mappings of addresses to Matrix User IDs. Addresses which do not have associations will not be included, which can make this property be an empty object.

Example request:

POST /_matrix/identity/v2/lookup HTTP/1.1
Content-Type: application/json

{
  "algorithm": "sha256",
  "pepper": "matrixrocks",
  "addresses": [
    "4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc",
    "nlo35_T5fzSGZzJApqu8lgIudJvmOQtDaHtr-I4rU7I"
  ]
}

Responses:

Status code 200:

The associations for any matched addresses.

Example

{
  "mappings": {
    "4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc": "@alice:example.org"
  }
}

Status code 400:

The client's request was invalid in some way. One possible problem could be the pepper being invalid after the server has rotated it - this is presented with the M_INVALID_PEPPER error code. Clients SHOULD make a call to /hash_details to get a new pepper in this scenario, being careful to avoid retry loops. M_INVALID_PARAM can also be returned to indicate the client supplied an algorithm that is unknown to the server.

Example

{
  "errcode": "M_INVALID_PEPPER",
  "error": "Unknown or invalid pepper - has it been rotated?"
}

11.5   Client behaviour

Note

This section only covers the v2 lookup endpoint. The v1 endpoint is described in isolation above.

Prior to performing a lookup clients SHOULD make a request to the /hash_details endpoint to determine what algorithms the server supports (described in more detail below). The client then uses this information to form a /lookup request and receive known bindings from the server.

Clients MUST support at least the sha256 algorithm.

11.6   Server behaviour

Note

This section only covers the v2 lookup endpoint. The v1 endpoint is described in isolation above.

Servers, upon receipt of a /lookup request, will compare the query against known bindings it has, hashing the identifiers it knows about as needed to verify exact matches to the request.

Servers MUST support at least the sha256 algorithm.

11.7   Algorithms

Some algorithms are defined as part of the specification, however other formats can be negotiated between the client and server using /hash_details.

11.7.1   sha256

This algorithm MUST be supported by clients and servers at a minimum. It is additionally the preferred algorithm for lookups.

When using this algorithm, the client converts the query first into strings separated by spaces in the format <address> <medium> <pepper>. The <pepper> is retrieved from /hash_details, the <medium> is typically email or msisdn (both lowercase), and the <address> is the 3PID to search for. For example, if the client wanted to know about alice@example.org's bindings, it would first format the query as alice@example.org email ThePepperGoesHere.

Rationale

Mediums and peppers are appended to the address to prevent a common prefix for each 3PID, helping prevent attackers from pre-computing the internal state of the hash function.

After formatting each query, the string is run through SHA-256 as defined by RFC 4634. The resulting bytes are then encoded using URL-Safe Unpadded Base64 (similar to room version 4's event ID format).

An example set of queries when using the pepper matrixrocks would be:

"alice@example.com email matrixrocks" -> "4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc"
"bob@example.com email matrixrocks"   -> "LJwSazmv46n0hlMlsb_iYxI0_HXEqy_yj6Jm636cdT8"
"18005552067 msisdn matrixrocks"      -> "nlo35_T5fzSGZzJApqu8lgIudJvmOQtDaHtr-I4rU7I"

The set of hashes is then given as the addresses array in /lookup. Note that the pepper used MUST be supplied as pepper in the /lookup request.

11.7.2   none

This algorithm performs plaintext lookups on the identity server. Typically this algorithm should not be used due to the security concerns of unhashed identifiers, however some scenarios (such as LDAP-backed identity servers) prevent the use of hashed identifiers. Identity servers (and optionally clients) can use this algorithm to perform those kinds of lookups.

Similar to the sha256 algorithm, the client converts the queries into strings separated by spaces in the format <address> <medium> - note the lack of <pepper>. For example, if the client wanted to know about alice@example.org's bindings, it would format the query as alice@example.org email.

The formatted strings are then given as the addresses in /lookup. Note that the pepper is still required, and must be provided to ensure the client has made an appropriate request to /hash_details first.

11.8   Security considerations

Note

MSC2134 has much more information about the security considerations made for this section of the specification. This section covers the high-level details for why the specification is the way it is.

Typically the lookup endpoint is used when a client has an unknown 3PID it wants to find a Matrix User ID for. Clients normally do this kind of lookup when inviting new users to a room or searching a user's address book to find any Matrix users they may not have discovered yet. Rogue or malicious identity servers could harvest this unknown information and do nefarious things with it if it were sent in plain text. In order to protect the privacy of users who might not have a Matrix identifier bound to their 3PID addresses, the specification attempts to make it difficult to harvest 3PIDs.

Rationale

Hashing identifiers, while not perfect, helps make the effort required to harvest identifiers significantly higher. Phone numbers in particular are still difficult to protect with hashing, however hashing is objectively better than not.

An alternative to hashing would be using bcrypt or similar with many rounds, however by nature of needing to serve mobile clients and clients on limited hardware the solution needs be kept relatively lightweight.

Clients should be cautious of servers not rotating their pepper very often, and potentially of servers which use a weak pepper - these servers may be attempting to brute force the identifiers or use rainbow tables to mine the addresses. Similarly, clients which support the none algorithm should consider at least warning the user of the risks in sending identifiers in plain text to the identity server.

Addresses are still potentially reversable using a calculated rainbow table given some identifiers, such as phone numbers, common email address domains, and leaked addresses are easily calculated. For example, phone numbers can have roughly 12 digits to them, making them an easier target for attack than email addresses.

12   Establishing associations

The flow for creating an association is session-based.

Within a session, one may prove that one has ownership of a 3PID. Once this has been established, the user can form an association between that 3PID and a Matrix user ID. Note that this association is only proved one way; a user can associate any Matrix user ID with a validated 3PID, i.e. I can claim that any email address I own is associated with @billg:microsoft.com.

Sessions are time-limited; a session is considered to have been modified when it was created, and then when a validation is performed within it. A session can only be checked for validation, and validation can only be performed within a session, within a 24 hour period since its most recent modification. Any attempts to perform these actions after the expiry will be rejected, and a new session should be created and used instead.

To start a session, the client makes a request to the appropriate /requestToken endpoint. The identity server then sends a validation token to the user, and the user provides the token to the client. The client then provides the token to the appropriate /submitToken endpoint, completing the session. At this point, the client should /bind the third party identifier or leave it for another entity to bind.

12.1   Format of a validation token

The format of the validation token is left up to the identity server: it should choose one appropriate to the 3PID type. (For example, it would be inappropriate to expect a user to copy a long passphrase including punctuation from an SMS message into a client.)

Whatever format the identity server uses, the validation token must consist of at most 255 Unicode codepoints. Clients must pass the token through without modification.

12.2   Email associations

12.2.1   Deprecated: POST /_matrix/identity/api/v1/validate/email/requestToken

Warning

This API is deprecated and will be removed from a future release.

Create a session for validating an email address.

The identity server will send an email containing a token. If that token is presented to the identity server in the future, it indicates that that user was able to read the email for that email address, and so we validate ownership of the email address.

Note that homeservers offer APIs that proxy this API, adding additional behaviour on top, for example, /register/email/requestToken is designed specifically for use when registering an account and therefore will inform the user if the email address given is already registered on the server.

Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specified as application/x-form-www-urlencoded data. However, this usage is deprecated.

Rate-limited:No.
Requires auth:No.

Request format:

Parameter Type Description
JSON body parameters
client_secret string Required. A unique string generated by the client, and used to identify the validation attempt. It must be a string consisting of the characters [0-9a-zA-Z.=_-]. Its length must not exceed 255 characters and it must not be empty.
email string Required. The email address to validate.
send_attempt integer Required. The server will only send an email if the send_attempt is a number greater than the most recent one which it has seen, scoped to that email + client_secret pair. This is to avoid repeatedly sending the same email in the case of request retries between the POSTing user and the identity server. The client should increment this value if they desire a new email (e.g. a reminder) to be sent. If they do not, the server should respond with success but not resend the email.
next_link string Optional. When the validation is completed, the identity server will redirect the user to this URL. This option is ignored when submitting 3PID validation information through a POST request.

Response format:

Parameter Type Description
sid string Required. The session ID. Session IDs are opaque strings generated by the identity server. They must consist entirely of the characters [0-9a-zA-Z.=_-]. Their length must not exceed 255 characters and they must not be empty.

Example request:

POST /_matrix/identity/api/v1/validate/email/requestToken HTTP/1.1
Content-Type: application/json

{
  "client_secret": "monkeys_are_GREAT",
  "email": "foo@example.com",
  "send_attempt": 1
}

Responses:

Status code 200:

Session created.

Example

{
  "sid": "123abc"
}

Status code 400:

An error ocurred. Some possible errors are:

  • M_INVALID_EMAIL: The email address provided was invalid.
  • M_EMAIL_SEND_ERROR: The validation email could not be sent.

Example

{
  "errcode": "M_INVALID_EMAIL",
  "error": "The email address is not valid"
}

12.2.2   Deprecated: POST /_matrix/identity/api/v1/validate/email/submitToken

Warning

This API is deprecated and will be removed from a future release.

Validate ownership of an email address.

If the three parameters are consistent with a set generated by a requestToken call, ownership of the email address is considered to have been validated. This does not publish any information publicly, or associate the email address with any Matrix user ID. Specifically, calls to /lookup will not show a binding.

The identity server is free to match the token case-insensitively, or carry out other mapping operations such as unicode normalisation. Whether to do so is an implementation detail for the identity server. Clients must always pass on the token without modification.

Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specified as application/x-form-www-urlencoded data. However, this usage is deprecated.

Rate-limited:No.
Requires auth:No.

Request format:

Parameter Type Description
JSON body parameters
sid string Required. The session ID, generated by the requestToken call.
client_secret string Required. The client secret that was supplied to the requestToken call.
token string Required. The token generated by the requestToken call and emailed to the user.

Response format:

Parameter Type Description
success boolean Required. Whether the validation was successful or not.

Example request:

POST /_matrix/identity/api/v1/validate/email/submitToken HTTP/1.1
Content-Type: application/json

{
  "sid": "1234",
  "client_secret": "monkeys_are_GREAT",
  "token": "atoken"
}

Response:

Status code 200:

The success of the validation.

Example

{
  "success": true
}

12.2.3   Deprecated: GET /_matrix/identity/api/v1/validate/email/submitToken

Warning

This API is deprecated and will be removed from a future release.

Validate ownership of an email address.

If the three parameters are consistent with a set generated by a requestToken call, ownership of the email address is considered to have been validated. This does not publish any information publicly, or associate the email address with any Matrix user ID. Specifically, calls to /lookup will not show a binding.

Note that, in contrast with the POST version, this endpoint will be used by end-users, and so the response should be human-readable.

Rate-limited:No.
Requires auth:No.

Request format:

Parameter Type Description
query parameters
sid string Required. The session ID, generated by the requestToken call.
client_secret string Required. The client secret that was supplied to the requestToken call.
token string Required. The token generated by the requestToken call and emailed to the user.

Example request:

GET /_matrix/identity/api/v1/validate/email/submitToken?sid=1234&client_secret=monkeys_are_GREAT&token=atoken HTTP/1.1

Responses:

Status code 200:

Email address is validated.

Status code 3xx:

Email address is validated, and the next_link parameter was provided to the requestToken call. The user must be redirected to the URL provided by the next_link parameter.

Status code 4xx:

Validation failed.

12.2.4   POST /_matrix/identity/v2/validate/email/requestToken

Create a session for validating an email address.

The identity server will send an email containing a token. If that token is presented to the identity server in the future, it indicates that that user was able to read the email for that email address, and so we validate ownership of the email address.

Note that homeservers offer APIs that proxy this API, adding additional behaviour on top, for example, /register/email/requestToken is designed specifically for use when registering an account and therefore will inform the user if the email address given is already registered on the server.

Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specified as application/x-form-www-urlencoded data. However, this usage is deprecated.

Rate-limited:No.
Requires auth:Yes.

Request format:

Parameter Type Description
JSON body parameters
client_secret string Required. A unique string generated by the client, and used to identify the validation attempt. It must be a string consisting of the characters [0-9a-zA-Z.=_-]. Its length must not exceed 255 characters and it must not be empty.
email string Required. The email address to validate.
send_attempt integer Required. The server will only send an email if the send_attempt is a number greater than the most recent one which it has seen, scoped to that email + client_secret pair. This is to avoid repeatedly sending the same email in the case of request retries between the POSTing user and the identity server. The client should increment this value if they desire a new email (e.g. a reminder) to be sent. If they do not, the server should respond with success but not resend the email.
next_link string Optional. When the validation is completed, the identity server will redirect the user to this URL. This option is ignored when submitting 3PID validation information through a POST request.

Response format:

Parameter Type Description
sid string Required. The session ID. Session IDs are opaque strings generated by the identity server. They must consist entirely of the characters [0-9a-zA-Z.=_-]. Their length must not exceed 255 characters and they must not be empty.

Example request:

POST /_matrix/identity/v2/validate/email/requestToken HTTP/1.1
Content-Type: application/json

{
  "client_secret": "monkeys_are_GREAT",
  "email": "foo@example.com",
  "send_attempt": 1
}

Responses:

Status code 200:

Session created.

Example

{
  "sid": "123abc"
}

Status code 400:

An error ocurred. Some possible errors are:

  • M_INVALID_EMAIL: The email address provided was invalid.
  • M_EMAIL_SEND_ERROR: The validation email could not be sent.

Example

{
  "errcode": "M_INVALID_EMAIL",
  "error": "The email address is not valid"
}

Status code 403:

The user must do something in order to use this endpoint. One example is an M_TERMS_NOT_SIGNED error where the user must agree to more terms.

Example

{
  "errcode": "M_TERMS_NOT_SIGNED",
  "error": "Please accept our updated terms of service before continuing"
}

12.2.5   POST /_matrix/identity/v2/validate/email/submitToken

Validate ownership of an email address.

If the three parameters are consistent with a set generated by a requestToken call, ownership of the email address is considered to have been validated. This does not publish any information publicly, or associate the email address with any Matrix user ID. Specifically, calls to /lookup will not show a binding.

The identity server is free to match the token case-insensitively, or carry out other mapping operations such as unicode normalisation. Whether to do so is an implementation detail for the identity server. Clients must always pass on the token without modification.

Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specified as application/x-form-www-urlencoded data. However, this usage is deprecated.

Rate-limited:No.
Requires auth:Yes.

Request format:

Parameter Type Description
JSON body parameters
sid string Required. The session ID, generated by the requestToken call.
client_secret string Required. The client secret that was supplied to the requestToken call.
token string Required. The token generated by the requestToken call and emailed to the user.

Response format:

Parameter Type Description
success boolean Required. Whether the validation was successful or not.

Example request:

POST /_matrix/identity/v2/validate/email/submitToken HTTP/1.1
Content-Type: application/json

{
  "sid": "1234",
  "client_secret": "monkeys_are_GREAT",
  "token": "atoken"
}

Responses:

Status code 200:

The success of the validation.

Example

{
  "success": true
}

Status code 403:

The user must do something in order to use this endpoint. One example is an M_TERMS_NOT_SIGNED error where the user must agree to more terms.

Example

{
  "errcode": "M_TERMS_NOT_SIGNED",
  "error": "Please accept our updated terms of service before continuing"
}

12.2.6   GET /_matrix/identity/v2/validate/email/submitToken

Validate ownership of an email address.

If the three parameters are consistent with a set generated by a requestToken call, ownership of the email address is considered to have been validated. This does not publish any information publicly, or associate the email address with any Matrix user ID. Specifically, calls to /lookup will not show a binding.

Note that, in contrast with the POST version, this endpoint will be used by end-users, and so the response should be human-readable.

Rate-limited:No.
Requires auth:Yes.

Request format:

Parameter Type Description
query parameters
sid string Required. The session ID, generated by the requestToken call.
client_secret string Required. The client secret that was supplied to the requestToken call.
token string Required. The token generated by the requestToken call and emailed to the user.

Example request:

GET /_matrix/identity/v2/validate/email/submitToken?sid=1234&client_secret=monkeys_are_GREAT&token=atoken HTTP/1.1

Responses:

Status code 200:

Email address is validated.

Status code 3xx:

Email address is validated, and the next_link parameter was provided to the requestToken call. The user must be redirected to the URL provided by the next_link parameter.

Status code 403:

The user must do something in order to use this endpoint. One example is an M_TERMS_NOT_SIGNED error where the user must agree to more terms.

Example

{
  "errcode": "M_TERMS_NOT_SIGNED",
  "error": "Please accept our updated terms of service before continuing"
}

Status code 4xx:

Validation failed.

12.3   Phone number associations

12.3.1   Deprecated: POST /_matrix/identity/api/v1/validate/msisdn/requestToken

Warning

This API is deprecated and will be removed from a future release.

Create a session for validating a phone number.

The identity server will send an SMS message containing a token. If that token is presented to the identity server in the future, it indicates that that user was able to read the SMS for that phone number, and so we validate ownership of the phone number.

Note that homeservers offer APIs that proxy this API, adding additional behaviour on top, for example, /register/msisdn/requestToken is designed specifically for use when registering an account and therefore will inform the user if the phone number given is already registered on the server.

Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specified as application/x-form-www-urlencoded data. However, this usage is deprecated.

Rate-limited:No.
Requires auth:No.

Request format:

Parameter Type Description
JSON body parameters
client_secret string Required. A unique string generated by the client, and used to identify the validation attempt. It must be a string consisting of the characters [0-9a-zA-Z.=_-]. Its length must not exceed 255 characters and it must not be empty.
country string Required. The two-letter uppercase ISO-3166-1 alpha-2 country code that the number in phone_number should be parsed as if it were dialled from.
phone_number string Required. The phone number to validate.
send_attempt integer Required. The server will only send an SMS if the send_attempt is a number greater than the most recent one which it has seen, scoped to that country + phone_number + client_secret triple. This is to avoid repeatedly sending the same SMS in the case of request retries between the POSTing user and the identity server. The client should increment this value if they desire a new SMS (e.g. a reminder) to be sent.
next_link string Optional. When the validation is completed, the identity server will redirect the user to this URL. This option is ignored when submitting 3PID validation information through a POST request.

Response format:

Parameter Type Description
sid string Required. The session ID. Session IDs are opaque strings generated by the identity server. They must consist entirely of the characters [0-9a-zA-Z.=_-]. Their length must not exceed 255 characters and they must not be empty.

Example request:

POST /_matrix/identity/api/v1/validate/msisdn/requestToken HTTP/1.1
Content-Type: application/json

{
  "client_secret": "monkeys_are_GREAT",
  "country": "GB",
  "phone_number": "07700900001",
  "send_attempt": 1
}

Responses:

Status code 200:

Session created.

Example

{
  "sid": "123abc"
}

Status code 400:

An error ocurred. Some possible errors are:

  • M_INVALID_ADDRESS: The phone number provided was invalid.
  • M_SEND_ERROR: The validation SMS could not be sent.
  • M_DESTINATION_REJECTED: The identity server cannot deliver an SMS to the provided country or region.

Example

{
  "errcode": "M_INVALID_ADDRESS",
  "error": "The phone number is not valid"
}

12.3.2   Deprecated: POST /_matrix/identity/api/v1/validate/msisdn/submitToken

Warning

This API is deprecated and will be removed from a future release.

Validate ownership of a phone number.

If the three parameters are consistent with a set generated by a requestToken call, ownership of the phone number is considered to have been validated. This does not publish any information publicly, or associate the phone number address with any Matrix user ID. Specifically, calls to /lookup will not show a binding.

The identity server is free to match the token case-insensitively, or carry out other mapping operations such as unicode normalisation. Whether to do so is an implementation detail for the identity server. Clients must always pass on the token without modification.

Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specified as application/x-form-www-urlencoded data. However, this usage is deprecated.

Rate-limited:No.
Requires auth:No.

Request format:

Parameter Type Description
JSON body parameters
sid string Required. The session ID, generated by the requestToken call.
client_secret string Required. The client secret that was supplied to the requestToken call.
token string Required. The token generated by the requestToken call and sent to the user.

Response format:

Parameter Type Description
success boolean Required. Whether the validation was successful or not.

Example request:

POST /_matrix/identity/api/v1/validate/msisdn/submitToken HTTP/1.1
Content-Type: application/json

{
  "sid": "1234",
  "client_secret": "monkeys_are_GREAT",
  "token": "atoken"
}

Response:

Status code 200:

The success of the validation.

Example

{
  "success": true
}

12.3.3   Deprecated: GET /_matrix/identity/api/v1/validate/msisdn/submitToken

Warning

This API is deprecated and will be removed from a future release.

Validate ownership of a phone number.

If the three parameters are consistent with a set generated by a requestToken call, ownership of the phone number address is considered to have been validated. This does not publish any information publicly, or associate the phone number with any Matrix user ID. Specifically, calls to /lookup will not show a binding.

Note that, in contrast with the POST version, this endpoint will be used by end-users, and so the response should be human-readable.

Rate-limited:No.
Requires auth:No.

Request format:

Parameter Type Description
query parameters
sid string Required. The session ID, generated by the requestToken call.
client_secret string Required. The client secret that was supplied to the requestToken call.
token string Required. The token generated by the requestToken call and sent to the user.

Example request:

GET /_matrix/identity/api/v1/validate/msisdn/submitToken?sid=1234&client_secret=monkeys_are_GREAT&token=atoken HTTP/1.1

Responses:

Status code 200:

Phone number is validated.

Status code 3xx:

Phone number address is validated, and the next_link parameter was provided to the requestToken call. The user must be redirected to the URL provided by the next_link parameter.

Status code 4xx:

Validation failed.

12.3.4   POST /_matrix/identity/v2/validate/msisdn/requestToken

Create a session for validating a phone number.

The identity server will send an SMS message containing a token. If that token is presented to the identity server in the future, it indicates that that user was able to read the SMS for that phone number, and so we validate ownership of the phone number.

Note that homeservers offer APIs that proxy this API, adding additional behaviour on top, for example, /register/msisdn/requestToken is designed specifically for use when registering an account and therefore will inform the user if the phone number given is already registered on the server.

Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specified as application/x-form-www-urlencoded data. However, this usage is deprecated.

Rate-limited:No.
Requires auth:Yes.

Request format:

Parameter Type Description
JSON body parameters
client_secret string Required. A unique string generated by the client, and used to identify the validation attempt. It must be a string consisting of the characters [0-9a-zA-Z.=_-]. Its length must not exceed 255 characters and it must not be empty.
country string Required. The two-letter uppercase ISO-3166-1 alpha-2 country code that the number in phone_number should be parsed as if it were dialled from.
phone_number string Required. The phone number to validate.
send_attempt integer Required. The server will only send an SMS if the send_attempt is a number greater than the most recent one which it has seen, scoped to that country + phone_number + client_secret triple. This is to avoid repeatedly sending the same SMS in the case of request retries between the POSTing user and the identity server. The client should increment this value if they desire a new SMS (e.g. a reminder) to be sent.
next_link string Optional. When the validation is completed, the identity server will redirect the user to this URL. This option is ignored when submitting 3PID validation information through a POST request.

Response format:

Parameter Type Description
sid string Required. The session ID. Session IDs are opaque strings generated by the identity server. They must consist entirely of the characters [0-9a-zA-Z.=_-]. Their length must not exceed 255 characters and they must not be empty.

Example request:

POST /_matrix/identity/v2/validate/msisdn/requestToken HTTP/1.1
Content-Type: application/json

{
  "client_secret": "monkeys_are_GREAT",
  "country": "GB",
  "phone_number": "07700900001",
  "send_attempt": 1
}

Responses:

Status code 200:

Session created.

Example

{
  "sid": "123abc"
}

Status code 400:

An error ocurred. Some possible errors are:

  • M_INVALID_ADDRESS: The phone number provided was invalid.
  • M_SEND_ERROR: The validation SMS could not be sent.
  • M_DESTINATION_REJECTED: The identity server cannot deliver an SMS to the provided country or region.

Example

{
  "errcode": "M_INVALID_ADDRESS",
  "error": "The phone number is not valid"
}

Status code 403:

The user must do something in order to use this endpoint. One example is an M_TERMS_NOT_SIGNED error where the user must agree to more terms.

Example

{
  "errcode": "M_TERMS_NOT_SIGNED",
  "error": "Please accept our updated terms of service before continuing"
}

12.3.5   POST /_matrix/identity/v2/validate/msisdn/submitToken

Validate ownership of a phone number.

If the three parameters are consistent with a set generated by a requestToken call, ownership of the phone number is considered to have been validated. This does not publish any information publicly, or associate the phone number address with any Matrix user ID. Specifically, calls to /lookup will not show a binding.

The identity server is free to match the token case-insensitively, or carry out other mapping operations such as unicode normalisation. Whether to do so is an implementation detail for the identity server. Clients must always pass on the token without modification.

Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specified as application/x-form-www-urlencoded data. However, this usage is deprecated.

Rate-limited:No.
Requires auth:Yes.

Request format:

Parameter Type Description
JSON body parameters
sid string Required. The session ID, generated by the requestToken call.
client_secret string Required. The client secret that was supplied to the requestToken call.
token string Required. The token generated by the requestToken call and sent to the user.

Response format:

Parameter Type Description
success boolean Required. Whether the validation was successful or not.

Example request:

POST /_matrix/identity/v2/validate/msisdn/submitToken HTTP/1.1
Content-Type: application/json

{
  "sid": "1234",
  "client_secret": "monkeys_are_GREAT",
  "token": "atoken"
}

Responses:

Status code 200:

The success of the validation.

Example

{
  "success": true
}

Status code 403:

The user must do something in order to use this endpoint. One example is an M_TERMS_NOT_SIGNED error where the user must agree to more terms.

Example

{
  "errcode": "M_TERMS_NOT_SIGNED",
  "error": "Please accept our updated terms of service before continuing"
}

12.3.6   GET /_matrix/identity/v2/validate/msisdn/submitToken

Validate ownership of a phone number.

If the three parameters are consistent with a set generated by a requestToken call, ownership of the phone number address is considered to have been validated. This does not publish any information publicly, or associate the phone number with any Matrix user ID. Specifically, calls to /lookup will not show a binding.

Note that, in contrast with the POST version, this endpoint will be used by end-users, and so the response should be human-readable.

Rate-limited:No.
Requires auth:Yes.

Request format:

Parameter Type Description
query parameters
sid string Required. The session ID, generated by the requestToken call.
client_secret string Required. The client secret that was supplied to the requestToken call.
token string Required. The token generated by the requestToken call and sent to the user.

Example request:

GET /_matrix/identity/v2/validate/msisdn/submitToken?sid=1234&client_secret=monkeys_are_GREAT&token=atoken HTTP/1.1

Responses:

Status code 200:

Phone number is validated.

Status code 3xx:

Phone number address is validated, and the next_link parameter was provided to the requestToken call. The user must be redirected to the URL provided by the next_link parameter.

Status code 403:

The user must do something in order to use this endpoint. One example is an M_TERMS_NOT_SIGNED error where the user must agree to more terms.

Example

{
  "errcode": "M_TERMS_NOT_SIGNED",
  "error": "Please accept our updated terms of service before continuing"
}

Status code 4xx:

Validation failed.

12.4   General

12.4.1   Deprecated: GET /_matrix/identity/api/v1/3pid/getValidated3pid

Warning

This API is deprecated and will be removed from a future release.

Determines if a given 3pid has been validated by a user.

Rate-limited:No.
Requires auth:No.

Request format:

Parameter Type Description
query parameters
sid string Required. The Session ID generated by the requestToken call.
client_secret string Required. The client secret passed to the requestToken call.

Response format:

Parameter Type Description
medium string Required. The medium type of the 3pid.
address string Required. The address of the 3pid being looked up.
validated_at integer Required. Timestamp, in milliseconds, indicating the time that the 3pid was validated.

Example request:

GET /_matrix/identity/api/v1/3pid/getValidated3pid?sid=1234&client_secret=monkeys_are_GREAT HTTP/1.1

Responses:

Status code 200:

Validation information for the session.

Example

{
  "medium": "email",
  "validated_at": 1457622739026,
  "address": "louise@bobs.burgers"
}

Status code 400:

The session has not been validated.

If the session has not been validated, then errcode will be M_SESSION_NOT_VALIDATED. If the session has timed out, then errcode will be M_SESSION_EXPIRED.

Example

{
  "errcode": "M_SESSION_NOT_VALIDATED",
  "error": "This validation session has not yet been completed"
}

Status code 404:

The Session ID or client secret were not found.

Example

{
  "errcode": "M_NO_VALID_SESSION",
  "error": "No valid session was found matching that sid and client secret"
}

12.4.2   Deprecated: POST /_matrix/identity/api/v1/3pid/bind

Warning

This API is deprecated and will be removed from a future release.

Publish an association between a session and a Matrix user ID.

Future calls to /lookup for any of the session's 3pids will return this association.

Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specified as application/x-form-www-urlencoded data. However, this usage is deprecated.

Rate-limited:No.
Requires auth:No.

Request format:

Parameter Type Description
JSON body parameters
sid string Required. The Session ID generated by the requestToken call.
client_secret string Required. The client secret passed to the requestToken call.
mxid string Required. The Matrix user ID to associate with the 3pids.

Response format:

Parameter Type Description
address string Required. The 3pid address of the user being looked up.
medium string Required. The medium type of the 3pid.
mxid string Required. The Matrix user ID associated with the 3pid.
not_before integer Required. A unix timestamp before which the association is not known to be valid.
not_after integer Required. A unix timestamp after which the association is not known to be valid.
ts integer Required. The unix timestamp at which the association was verified.
signatures {string: {string: string}} Required. The signatures of the verifying identity servers which show that the association should be trusted, if you trust the verifying identity services.

Example request:

POST /_matrix/identity/api/v1/3pid/bind HTTP/1.1
Content-Type: application/json

{
  "sid": "1234",
  "client_secret": "monkeys_are_GREAT",
  "mxid": "@ears:matrix.org"
}

Responses:

Status code 200:

The association was published.

Example

{
  "address": "louise@bobs.burgers",
  "medium": "email",
  "mxid": "@ears:matrix.org",
  "not_before": 1428825849161,
  "not_after": 4582425849161,
  "ts": 1428825849161,
  "signatures": {
    "matrix.org": {
      "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
    }
  }
}

Status code 400:

The association was not published.

If the session has not been validated, then errcode will be M_SESSION_NOT_VALIDATED. If the session has timed out, then errcode will be M_SESSION_EXPIRED.

Example

{
  "errcode": "M_SESSION_NOT_VALIDATED",
  "error": "This validation session has not yet been completed"
}

Status code 404:

The Session ID or client secret were not found

Example

{
  "errcode": "M_NO_VALID_SESSION",
  "error": "No valid session was found matching that sid and client secret"
}

12.4.3   Deprecated: POST /_matrix/identity/api/v1/3pid/unbind

Warning

This API is deprecated and will be removed from a future release.

Remove an association between a session and a Matrix user ID.

Future calls to /lookup for any of the session's 3pids will not return the removed association.

The identity server should authenticate the request in one of two ways:

  1. The request is signed by the homeserver which controls the user_id.
  2. The request includes the sid and client_secret parameters, as per /3pid/bind, which proves ownership of the 3PID.

If this endpoint returns a JSON Matrix error, that error should be passed through to the client requesting an unbind through a homeserver, if the homeserver is acting on behalf of a client.

Rate-limited:No.
Requires auth:No.

Request format:

Parameter Type Description
JSON body parameters
sid string The Session ID generated by the requestToken call.
client_secret string The client secret passed to the requestToken call.
mxid string Required. The Matrix user ID to remove from the 3pids.
threepid 3PID Required. The 3PID to remove. Must match the 3PID used to generate the session if using sid and client_secret to authenticate this request.
3PID
Parameter Type Description
medium string Required. A medium from the 3PID Types Appendix, matching the medium of the identifier to unbind.
address string Required. The 3PID address to remove.

Example request:

POST /_matrix/identity/api/v1/3pid/unbind HTTP/1.1
Content-Type: application/json

{
  "sid": "1234",
  "client_secret": "monkeys_are_GREAT",
  "mxid": "@ears:example.org",
  "threepid": {
    "medium": "email",
    "address": "monkeys_have_ears@example.org"
  }
}

Responses:

Status code 200:

The association was successfully removed.

Example

{}

Status code 400:

If the response body is not a JSON Matrix error, the identity server does not support unbinds. If a JSON Matrix error is in the response body, the requesting party should respect the error.

Status code 403:

The credentials supplied to authenticate the request were invalid. This may also be returned if the identity server does not support the chosen authentication method (such as blocking homeservers from unbinding identifiers).

Example

{
  "errcode": "M_FORBIDDEN",
  "error": "Invalid homeserver signature"
}

Status code 404:

If the response body is not a JSON Matrix error, the identity server does not support unbinds. If a JSON Matrix error is in the response body, the requesting party should respect the error.

Status code 501:

If the response body is not a JSON Matrix error, the identity server does not support unbinds. If a JSON Matrix error is in the response body, the requesting party should respect the error.

12.4.4   GET /_matrix/identity/v2/3pid/getValidated3pid

Determines if a given 3pid has been validated by a user.

Rate-limited:No.
Requires auth:Yes.

Request format:

Parameter Type Description
query parameters
sid string Required. The Session ID generated by the requestToken call.
client_secret string Required. The client secret passed to the requestToken call.

Response format:

Parameter Type Description
medium string Required. The medium type of the 3pid.
address string Required. The address of the 3pid being looked up.
validated_at integer Required. Timestamp, in milliseconds, indicating the time that the 3pid was validated.

Example request:

GET /_matrix/identity/v2/3pid/getValidated3pid?sid=1234&client_secret=monkeys_are_GREAT HTTP/1.1

Responses:

Status code 200:

Validation information for the session.

Example

{
  "medium": "email",
  "validated_at": 1457622739026,
  "address": "louise@bobs.burgers"
}

Status code 400:

The session has not been validated.

If the session has not been validated, then errcode will be M_SESSION_NOT_VALIDATED. If the session has timed out, then errcode will be M_SESSION_EXPIRED.

Example

{
  "errcode": "M_SESSION_NOT_VALIDATED",
  "error": "This validation session has not yet been completed"
}

Status code 403:

The user must do something in order to use this endpoint. One example is an M_TERMS_NOT_SIGNED error where the user must agree to more terms.

Example

{
  "errcode": "M_TERMS_NOT_SIGNED",
  "error": "Please accept our updated terms of service before continuing"
}

Status code 404:

The Session ID or client secret were not found.

Example

{
  "errcode": "M_NO_VALID_SESSION",
  "error": "No valid session was found matching that sid and client secret"
}

12.4.5   POST /_matrix/identity/v2/3pid/bind

Publish an association between a session and a Matrix user ID.

Future calls to /lookup for any of the session's 3pids will return this association.

Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specified as application/x-form-www-urlencoded data. However, this usage is deprecated.

Rate-limited:No.
Requires auth:Yes.

Request format:

Parameter Type Description
JSON body parameters
sid string Required. The Session ID generated by the requestToken call.
client_secret string Required. The client secret passed to the requestToken call.
mxid string Required. The Matrix user ID to associate with the 3pids.

Response format:

Parameter Type Description
address string Required. The 3pid address of the user being looked up.
medium string Required. The medium type of the 3pid.
mxid string Required. The Matrix user ID associated with the 3pid.
not_before integer Required. A unix timestamp before which the association is not known to be valid.
not_after integer Required. A unix timestamp after which the association is not known to be valid.
ts integer Required. The unix timestamp at which the association was verified.
signatures {string: {string: string}} Required. The signatures of the verifying identity servers which show that the association should be trusted, if you trust the verifying identity services.

Example request:

POST /_matrix/identity/v2/3pid/bind HTTP/1.1
Content-Type: application/json

{
  "sid": "1234",
  "client_secret": "monkeys_are_GREAT",
  "mxid": "@ears:matrix.org"
}

Responses:

Status code 200:

The association was published.

Example

{
  "address": "louise@bobs.burgers",
  "medium": "email",
  "mxid": "@ears:matrix.org",
  "not_before": 1428825849161,
  "not_after": 4582425849161,
  "ts": 1428825849161,
  "signatures": {
    "matrix.org": {
      "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
    }
  }
}

Status code 400:

The association was not published.

If the session has not been validated, then errcode will be M_SESSION_NOT_VALIDATED. If the session has timed out, then errcode will be M_SESSION_EXPIRED.

Example

{
  "errcode": "M_SESSION_NOT_VALIDATED",
  "error": "This validation session has not yet been completed"
}

Status code 403:

The user must do something in order to use this endpoint. One example is an M_TERMS_NOT_SIGNED error where the user must agree to more terms.

Example

{
  "errcode": "M_TERMS_NOT_SIGNED",
  "error": "Please accept our updated terms of service before continuing"
}

Status code 404:

The Session ID or client secret were not found

Example

{
  "errcode": "M_NO_VALID_SESSION",
  "error": "No valid session was found matching that sid and client secret"
}

12.4.6   POST /_matrix/identity/v2/3pid/unbind

Remove an association between a session and a Matrix user ID.

Future calls to /lookup for any of the session's 3pids will not return the removed association.

The identity server should authenticate the request in one of two ways:

  1. The request is signed by the homeserver which controls the user_id.
  2. The request includes the sid and client_secret parameters, as per /3pid/bind, which proves ownership of the 3PID.

If this endpoint returns a JSON Matrix error, that error should be passed through to the client requesting an unbind through a homeserver, if the homeserver is acting on behalf of a client.

Rate-limited:No.
Requires auth:Yes.

Request format:

Parameter Type Description
JSON body parameters
sid string The Session ID generated by the requestToken call.
client_secret string The client secret passed to the requestToken call.
mxid string Required. The Matrix user ID to remove from the 3pids.
threepid 3PID Required. The 3PID to remove. Must match the 3PID used to generate the session if using sid and client_secret to authenticate this request.
3PID
Parameter Type Description
medium string Required. A medium from the 3PID Types Appendix, matching the medium of the identifier to unbind.
address string Required. The 3PID address to remove.

Example request:

POST /_matrix/identity/v2/3pid/unbind HTTP/1.1
Content-Type: application/json

{
  "sid": "1234",
  "client_secret": "monkeys_are_GREAT",
  "mxid": "@ears:example.org",
  "threepid": {
    "medium": "email",
    "address": "monkeys_have_ears@example.org"
  }
}

Responses:

Status code 200:

The association was successfully removed.

Example

{}

Status code 400:

If the response body is not a JSON Matrix error, the identity server does not support unbinds. If a JSON Matrix error is in the response body, the requesting party should respect the error.

Status code 403:

The credentials supplied to authenticate the request were invalid. This may also be returned if the identity server does not support the chosen authentication method (such as blocking homeservers from unbinding identifiers).

Another common error code is M_TERMS_NOT_SIGNED where the user needs to agree to more terms in order to continue.

Example

{
  "errcode": "M_FORBIDDEN",
  "error": "Invalid homeserver signature"
}

Status code 404:

If the response body is not a JSON Matrix error, the identity server does not support unbinds. If a JSON Matrix error is in the response body, the requesting party should respect the error.

Status code 501:

If the response body is not a JSON Matrix error, the identity server does not support unbinds. If a JSON Matrix error is in the response body, the requesting party should respect the error.

13   Invitation storage

An identity server can store pending invitations to a user's 3PID, which will be retrieved and can be either notified on or look up when the 3PID is associated with a Matrix user ID.

At a later point, if the owner of that particular 3PID binds it with a Matrix user ID, the identity server will attempt to make an HTTP POST to the Matrix user's homeserver via the /3pid/onbind endpoint. The request MUST be signed with a long-term private key for the identity server.

13.1   Deprecated: POST /_matrix/identity/api/v1/store-invite

Warning

This API is deprecated and will be removed from a future release.

Store pending invitations to a user's 3pid.

In addition to the request parameters specified below, an arbitrary number of other parameters may also be specified. These may be used in the invite message generation described below.

The service will generate a random token and an ephemeral key used for accepting the invite.

The service also generates a display_name for the inviter, which is a redacted version of address which does not leak the full contents of the address.

The service records persistently all of the above information.

It also generates an email containing all of this data, sent to the address parameter, notifying them of the invitation.

Also, the generated ephemeral public key will be listed as valid on requests to /_matrix/identity/api/v1/pubkey/ephemeral/isvalid.

Currently, invites may only be issued for 3pids of the email medium.

Optional fields in the request should be populated to the best of the server's ability. Identity servers may use these variables when notifying the address of the pending invite for display purposes.

Rate-limited:No.
Requires auth:No.

Request format:

Parameter Type Description
JSON body parameters
medium string Required. The literal string email.
address string Required. The email address of the invited user.
room_id string Required. The Matrix room ID to which the user is invited
sender string Required. The Matrix user ID of the inviting user
room_alias string The Matrix room alias for the room to which the user is invited. This should be retrieved from the m.room.canonical_alias state event.
room_avatar_url string The Content URI for the room to which the user is invited. This should be retrieved from the m.room.avatar state event.
room_join_rules string The join_rule for the room to which the user is invited. This should be retrieved from the m.room.join_rules state event.
room_name string The name of the room to which the user is invited. This should be retrieved from the m.room.name state event.
sender_display_name string The display name of the user ID initiating the invite.
sender_avatar_url string The Content URI for the avatar of the user ID initiating the invite.

Response format:

Parameter Type Description
token string Required. The generated token. Must be a string consisting of the characters [0-9a-zA-Z.=_-]. Its length must not exceed 255 characters and it must not be empty.
public_keys [string] Required. A list of [server's long-term public key, generated ephemeral public key].
display_name string Required. The generated (redacted) display_name.

Example request:

POST /_matrix/identity/api/v1/store-invite HTTP/1.1
Content-Type: application/json

{
  "medium": "email",
  "address": "foo@example.com",
  "room_id": "!something:example.org",
  "sender": "@bob:example.com",
  "room_alias": "#somewhere:exmaple.org",
  "room_avatar_url": "mxc://example.org/s0meM3dia",
  "room_join_rules": "public",
  "room_name": "Bob's Emporium of Messages",
  "sender_display_name": "Bob Smith",
  "sender_avatar_url": "mxc://example.org/an0th3rM3dia"
}

Responses:

Status code 200:

The invitation was stored.

Example

{
  "application/json": {
    "token": "sometoken",
    "public_keys": [
      "serverpublickey",
      "ephemeralpublickey"
    ],
    "display_name": "f...@b..."
  }
}

Status code 400:

An error has occured.

If the 3pid is already bound to a Matrix user ID, the error code will be M_THREEPID_IN_USE. If the medium is unsupported, the error code will be M_UNRECOGNIZED.

Example

{
  "errcode": "M_THREEPID_IN_USE",
  "error": "Binding already known",
  "mxid": "@alice:example.com"
}

13.2   POST /_matrix/identity/v2/store-invite

Store pending invitations to a user's 3pid.

In addition to the request parameters specified below, an arbitrary number of other parameters may also be specified. These may be used in the invite message generation described below.

The service will generate a random token and an ephemeral key used for accepting the invite.

The service also generates a display_name for the inviter, which is a redacted version of address which does not leak the full contents of the address.

The service records persistently all of the above information.

It also generates an email containing all of this data, sent to the address parameter, notifying them of the invitation.

Also, the generated ephemeral public key will be listed as valid on requests to /_matrix/identity/v2/pubkey/ephemeral/isvalid.

Currently, invites may only be issued for 3pids of the email medium.

Optional fields in the request should be populated to the best of the server's ability. Identity servers may use these variables when notifying the address of the pending invite for display purposes.

Rate-limited:No.
Requires auth:Yes.

Request format:

Parameter Type Description
JSON body parameters
medium string Required. The literal string email.
address string Required. The email address of the invited user.
room_id string Required. The Matrix room ID to which the user is invited
sender string Required. The Matrix user ID of the inviting user
room_alias string The Matrix room alias for the room to which the user is invited. This should be retrieved from the m.room.canonical_alias state event.
room_avatar_url string The Content URI for the room to which the user is invited. This should be retrieved from the m.room.avatar state event.
room_join_rules string The join_rule for the room to which the user is invited. This should be retrieved from the m.room.join_rules state event.
room_name string The name of the room to which the user is invited. This should be retrieved from the m.room.name state event.
sender_display_name string The display name of the user ID initiating the invite.
sender_avatar_url string The Content URI for the avatar of the user ID initiating the invite.

Response format:

Parameter Type Description
token string Required. The generated token. Must be a string consisting of the characters [0-9a-zA-Z.=_-]. Its length must not exceed 255 characters and it must not be empty.
public_keys [string] Required. A list of [server's long-term public key, generated ephemeral public key].
display_name string Required. The generated (redacted) display_name.

Example request:

POST /_matrix/identity/v2/store-invite HTTP/1.1
Content-Type: application/json

{
  "medium": "email",
  "address": "foo@example.com",
  "room_id": "!something:example.org",
  "sender": "@bob:example.com",
  "room_alias": "#somewhere:exmaple.org",
  "room_avatar_url": "mxc://example.org/s0meM3dia",
  "room_join_rules": "public",
  "room_name": "Bob's Emporium of Messages",
  "sender_display_name": "Bob Smith",
  "sender_avatar_url": "mxc://example.org/an0th3rM3dia"
}

Responses:

Status code 200:

The invitation was stored.

Example

{
  "application/json": {
    "token": "sometoken",
    "public_keys": [
      "serverpublickey",
      "ephemeralpublickey"
    ],
    "display_name": "f...@b..."
  }
}

Status code 400:

An error has occured.

If the 3pid is already bound to a Matrix user ID, the error code will be M_THREEPID_IN_USE. If the medium is unsupported, the error code will be M_UNRECOGNIZED.

Example

{
  "errcode": "M_THREEPID_IN_USE",
  "error": "Binding already known",
  "mxid": "@alice:example.com"
}

Status code 403:

The user must do something in order to use this endpoint. One example is an M_TERMS_NOT_SIGNED error where the user must agree to more terms.

Example

{
  "errcode": "M_TERMS_NOT_SIGNED",
  "error": "Please accept our updated terms of service before continuing"
}

14   Ephemeral invitation signing

To aid clients who may not be able to perform crypto themselves, the identity server offers some crypto functionality to help in accepting invitations. This is less secure than the client doing it itself, but may be useful where this isn't possible.

14.1   Deprecated: POST /_matrix/identity/api/v1/sign-ed25519

Warning

This API is deprecated and will be removed from a future release.

Sign invitation details.

The identity server will look up token which was stored in a call to store-invite, and fetch the sender of the invite.

Rate-limited:No.
Requires auth:No.

Request format:

Parameter Type Description
JSON body parameters
mxid string Required. The Matrix user ID of the user accepting the invitation.
token string Required. The token from the call to store- invite.
private_key string Required. The private key, encoded as Unpadded base64.

Response format:

Parameter Type Description
mxid string Required. The Matrix user ID of the user accepting the invitation.
sender string Required. The Matrix user ID of the user who sent the invitation.
signatures {string: {string: string}} Required. The signature of the mxid, sender, and token.
token string Required. The token for the invitation.

Example request:

POST /_matrix/identity/api/v1/sign-ed25519 HTTP/1.1
Content-Type: application/json

{
  "mxid": "@foo:bar.com",
  "token": "sometoken",
  "private_key": "base64encodedkey"
}

Responses:

Status code 200:

The signed JSON of the mxid, sender, and token.

Example

{
  "mxid": "@foo:bar.com",
  "sender": "@baz:bar.com",
  "signatures": {
    "my.id.server": {
      "ed25519:0": "def987"
    }
  },
  "token": "abc123"
}

Status code 404:

The token was not found.

Example

{
  "errcode": "M_UNRECOGNIZED",
  "error": "Didn't recognize token"
}

14.2   POST /_matrix/identity/v2/sign-ed25519

Sign invitation details.

The identity server will look up token which was stored in a call to store-invite, and fetch the sender of the invite.

Rate-limited:No.
Requires auth:Yes.

Request format:

Parameter Type Description
JSON body parameters
mxid string Required. The Matrix user ID of the user accepting the invitation.
token string Required. The token from the call to store- invite.
private_key string Required. The private key, encoded as Unpadded base64.

Response format:

Parameter Type Description
mxid string Required. The Matrix user ID of the user accepting the invitation.
sender string Required. The Matrix user ID of the user who sent the invitation.
signatures {string: {string: string}} Required. The signature of the mxid, sender, and token.
token string Required. The token for the invitation.

Example request:

POST /_matrix/identity/v2/sign-ed25519 HTTP/1.1
Content-Type: application/json

{
  "mxid": "@foo:bar.com",
  "token": "sometoken",
  "private_key": "base64encodedkey"
}

Responses:

Status code 200:

The signed JSON of the mxid, sender, and token.

Example

{
  "mxid": "@foo:bar.com",
  "sender": "@baz:bar.com",
  "signatures": {
    "my.id.server": {
      "ed25519:0": "def987"
    }
  },
  "token": "abc123"
}

Status code 403:

The user must do something in order to use this endpoint. One example is an M_TERMS_NOT_SIGNED error where the user must agree to more terms.

Example

{
  "errcode": "M_TERMS_NOT_SIGNED",
  "error": "Please accept our updated terms of service before continuing"
}

Status code 404:

The token was not found.

Example

{
  "errcode": "M_UNRECOGNIZED",
  "error": "Didn't recognize token"
}