rest.md

REST backend

The REST backend allows you to query identity data in existing webapps, like:

• Forums (phpBB, Discourse, etc.)
• Custom Identity stores (Keycloak, ...)
• CRMs (Wordpress, ...)
• self-hosted clouds (Nextcloud, ownCloud, ...)

It supports the following mxisd flows:

• Authentication
• Directory
• Identity

To integrate this backend with your webapp, you will need to implement three specific REST endpoints detailed below.

Configuration

Key	Default	Description
rest.enabled	false	Globally enable/disable the REST backend
rest.host	empty	Default base URL to use for the different endpoints.
rest.endpoints.auth	/_mxisd/backend/api/v1/auth/login	Validate credentials and get user profile
rest.endpoints.directory	/_mxisd/backend/api/v1/directory/user/search	Search for users by arbitrary input
rest.endpoints.identity.single	/_mxisd/backend/api/v1/identity/single	Endpoint to query a single 3PID
rest.endpoints.identity.bulk	/_mxisd/backend/api/v1/identity/bulk	Endpoint to query a list of 3PID

Endpoint values can handle two formats:

• URL Path starting with / that gets happened to the rest.host
• Full URL, if you want each endpoint to go to a specific server/protocol/port

rest.host is mandatory if at least one endpoint is not a full URL.

Endpoints

Authentication

HTTP method: POST
Content-type: JSON UTF-8

Request Body

{
  "auth": {
    "mxid": "@john.doe:example.org",
    "localpart": "john.doe",
    "domain": "example.org",
    "password": "passwordOfTheUser"
  }
}

Response Body

If the authentication fails:

{
  "auth": {
    "success": false
  }
}

If the authentication succeed:

• auth.id supported values: localpart, mxid
• auth.profile and any sub-member are all optional

{
  "auth": {
    "success": true,
    "id": {
      "type": "localpart",
      "value": "john"
    },
    "profile": {
      "display_name": "John Doe",
      "three_pids": [
        {
          "medium": "email",
          "address": "[email protected]"
        },
        {
          "medium": "msisdn",
          "address": "123456789"
        }
      ]
    }
  }
}

Directory

HTTP method: POST Content-type: JSON UTF-8

Request Body

{
  "by": "<search type>",
  "search_term": "doe"
}

by can be:

• name
• threepid

Response Body:

If users found:

{
  "limited": false,
  "results": [
    {
      "avatar_url": "http://domain.tld/path/to/avatar.png",
      "display_name": "John Doe",
      "user_id": "UserIdLocalpart"
    },
    {
      ...
    }
  ]
}

If no user found:

{
  "limited": false,
  "results": []
}

Identity

Single 3PID lookup

HTTP method: POST
Content-type: JSON UTF-8

Request Body

{
  "lookup": {
    "medium": "email",
    "address": "[email protected]"
  }
}

Response Body

If a match was found:

• lookup.id.type supported values: localpart, mxid

{
  "lookup": {
    "medium": "email",
    "address": "[email protected]",
    "id": {
      "type": "mxid",
      "value": "@john:example.org"
    }
  }
}

If no match was found:

{}

Bulk 3PID lookup

HTTP method: POST
Content-type: JSON UTF-8

Request Body

{
  "lookup": [
    {
      "medium": "email",
      "address": "[email protected]"
    },
    {
      "medium": "msisdn",
      "address": "123456789"
    }
  ]
}

Response Body

For all entries where a match was found:

• lookup[].id.type supported values: localpart, mxid

{
  "lookup": [
    {
      "medium": "email",
      "address": "[email protected]",
      "id": {
        "type": "localpart",
        "value": "john"
      }
    },
    {
      "medium": "msisdn",
      "address": "123456789",
      "id": {
        "type": "mxid",
        "value": "@jane:example.org"
      }
    }
  ]
}

If no match was found:

{
  "lookup": []
}