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.

Table of Contents

1   Specification version

This version of the specification is generated from matrix-doc as of Git commit msisdn,82521a0.

2   General principles

The purpose of an identity service 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 service 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 service.

In general, identity services 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 service is left as an exercise for the client.

3PID types are described in 3PID Types Appendix.

3   Privacy

Identity is a privacy-sensitive issue. While the identity service 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).

4   Status check

4.1   GET /_matrix/identity/api/v1

Checks that an Identity server is available at this API endpopint.

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.

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

{}

5   Key management

An identity service has some long-term public-private keypairs. These are named in a scheme algorithm:identifier, e.g. ed25519:0. When signing an association, the Matrix standard JSON signing format is used, as specified in the server-server API specification under the heading "Signing Events".

In the event of key compromise, the identity service may revoke any of its keys. An HTTP API is offered to get public keys, and check whether a particular key is valid.

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.

5.1   GET /_matrix/identity/api/v1/pubkey/{keyId}

Get the public key for the passed key ID.

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  

Example request:

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

Response:

Status code 200:

The public key exists.

Example

{
  "public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
}

5.2   GET /_matrix/identity/api/v1/pubkey/isvalid

Check whether a long-term public key is valid.

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

5.3   GET /_matrix/identity/api/v1/pubkey/ephemeral/isvalid

Check whether a short-term public key is valid.

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

6   Association Lookup

6.1   GET /_matrix/identity/api/v1/lookup

Look up the Matrix user ID for a 3pid.

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 The 3pid address of the user being looked up.
medium string The literal string "email".
mxid string The Matrix user ID associated with the 3pid.
not_before integer A unix timestamp before which the association is not known to be valid.
not_after integer A unix timestamp after which the association is not known to be valid.
ts integer The unix timestamp at which the association was verified.
signatures object The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services.

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

6.2   POST /_matrix/identity/api/v1/bulk_lookup

Lookup Matrix user IDs for a list of 3pids.

Request format:

Parameter Type Description
JSON body parameters
threepids [[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]] Required. an array of array containing the 3PID Types with the medium in first position, the address in second position and Matrix 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"
    ]
  ]
}

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

7.1   Email associations

7.1.1   POST /_matrix/identity/api/v1/validate/email/requestToken

Create a session for validating an email address.

The identity service will send an email containing a token. If that token is presented to the identity service 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 Home Servers 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 older versions of this specification, the parameters may also be specified as application/x-form-www-urlencoded data. However, this usage is deprecated.

Request format:

Parameter Type Description
JSON body parameters
client_secret string Required. A unique string used to identify the validation attempt
email string Required. The email address to validate.
send_attempt integer Optional. If specified, the server will only send an email if the send_attempt is a number greater than the most recent one which it has seen (or if it has never seen one), 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 service. The client should increment this value if they desire a new email (e.g. a reminder) to be sent.
next_link string Optional. When the validation is completed, the identity service will redirect the user to this URL.

Response format:

Parameter Type Description
sid string The session ID.

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
}

Response:

Status code 200:

Session created.

Example

{
  "sid": "1234"
}

7.1.2   POST /_matrix/identity/api/v1/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: for backwards compatibility with older versions of this specification, the parameters may also be specified as application/x-form-www-urlencoded data. However, this usage is deprecated.

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

7.1.3   GET /_matrix/identity/api/v1/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.

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.

7.2   General

7.2.1   GET /_matrix/identity/api/v1/3pid/getValidated3pid

A client can check whether ownership of a 3pid was validated

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 The medium type of the 3pid.
address string The address of the 3pid being looked up.
validated_at integer Timestamp 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"
}

7.2.2   POST /_matrix/identity/api/v1/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 older versions of this specification, the parameters may also be specified as application/x-form-www-urlencoded data. However, this usage is deprecated.

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 The 3pid address of the user being looked up.
medium string The medium type of the 3pid.
mxid string The Matrix user ID associated with the 3pid.
not_before integer A unix timestamp before which the association is not known to be valid.
not_after integer A unix timestamp after which the association is not known to be valid.
ts integer The unix timestamp at which the association was verified.
signatures object The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services.

Example request:

POST /_matrix/identity/api/v1/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"
}

8   Invitation Storage

An identity service 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 which looks roughly as below:

POST https://bar.com:8448/_matrix/federation/v1/3pid/onbind
Content-Type: application/json

{
 "medium": "email",
 "address": "foo@bar.baz",
 "mxid": "@alice:example.tld",
 "invites": [
   {
     "medium": "email",
     "address": "foo@bar.baz",
     "mxid": "@alice:example.tld",
     "room_id": "!something:example.tld",
     "sender": "@bob:example.tld",
     "signed": {
       "mxid": "@alice:example.tld",
       "signatures": {
         "vector.im": {
           "ed25519:0": "somesignature"
         }
       },
       "token": "sometoken"
     }
   }
 ]
}

Where the signature is produced using a long-term private key.

8.1   POST /_matrix/identity/api/v1/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/api/v1/pubkey/ephemeral/isvalid.

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

Response format:

Parameter Type Description
token string The generated token.
public_keys [string] A list of [server's long-term public key, generated ephemeral public key].
display_name string 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@bar.baz",
  "room_id": "!something:example.tld",
  "sender": "@bob:example.com"
}

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 will occur if the 3pid is already bound to a Matrix user ID, or if the medium is unsupported.

Example

{
  "errcode": "THREEPID_IN_USE",
  "error": "Binding already known",
  "mxid": "mxid"
}

9   Ephemeral invitation signing

To aid clients who may not be able to perform crypto themselves, the identity service 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.

9.1   POST /_matrix/identity/api/v1/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.

Request format:

Parameter Type Description
JSON body parameters
mxid string Required. The Matrix user ID of the user accepting the invitation.
token string Required. 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 The Matrix user ID of the user accepting the invitation.
sender string The Matrix user ID of the user who sent the invitation.
signatures object The signature of ...

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 signature of ...

Example

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

Status code 404:

Token was not found.

The identity service will happily sign invitation details with a request-specified ed25519 private key for you, if you want it to. It takes URL-encoded POST parameters: - mxid (string, required) - token (string, required) - private_key (string, required): The private key, encoded as Unpadded base64.

It will look up token which was stored in a call to store-invite, and fetch the sender of the invite. It will then respond with JSON which looks something like:

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