Skip to main content

Getting Started Using the Client-Server API

The Synapse AdminClient-Server API allows administrationa ofuser yourto homeserver,perform suchany asaction managingthey users,could roomsvia anda media.Matrix client programatically. In order to make use of the API you will need to haveretrieve an adminaccess usertoken account present on the homeserver you wish to manage.

Promoting a Matrix Account to Admin

If you're an EMS customer, you can create / managefor your users via the Server Admin tab of the EMS Control Panel.

If you're an ESS customer, you can create / manage your users via your admin dashboard, or via the Admin tab available when running the installer.

Promote the user you will be using to Admin by clicking on the desired user, and checking the Admin checkbox and confirming.account.

Getting your access_token

In order to use the Synapse AdminClient-Server API you will need to authenticate your calls to the API using an access_token from an Adminyour user account. You can find your access_token from the Help & About section of your settings. Check out the Help & About page from the Element Web/Desktop Client Settings chapter for more guidance.

Making ana AdminClient-Server API request

Using your preferred method, you will need to authenticate each request to ana AdminClient-Server API endpoint by providing the token as either a query parameter or a request header. To add it as a request header in cURL, you can use the following, replacing syt_AjfVef2_L33JNpafeif_0feKJfeaf0CQpoZk with your own access_token:

curl --header "Authorization: Bearer syt_AjfVef2_L33JNpafeif_0feKJfeaf0CQpoZk" -X GET http:https://127.0.0.1:8008/_synapse/admin/v2/users/@foo:bar.HOMESERVER_URL/_matrix/client/v0/profile/@user:example.com

Here is the equivalent action using Python and the requests library:

import requests

headers = {
    'Authorization': 'Bearer syt_AjfVef2_L33JNpafeif_0feKJfeaf0CQpoZk',
}

response = requests.get('http:https://127.0.0.1:8008/_synapse/admin/v2/users/@foo:bar.HOMESERVER_URL/_matrix/client/v0/profile/@user:example.com', headers=headers)

Further details on the using the API are out-of-scope for this documentation, please consult the Synapse AdminClient-Server API documentation. You will find multiple sections covering its use, such as Rooms, Users and Media.

Back to top