Getting Started Using the Client-Server API

The Synapse Admin API allows administration of your homeserver, such as managing users, rooms and media. In order to make use of the API you will need to have an admin user account present on the homeserver you wish to manage.

Promoting a Matrix Account to Admin

If you're an EMS customer, you can create / manage 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.

Getting your access_token

In order to use the Synapse Admin API you will need to authenticate your calls to the API using an access_token from an Admin 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 an Admin API request

Using your preferred method, you will need to authenticate each request to an Admin 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://127.0.0.1:8008/_synapse/admin/v2/users/@foo:bar.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://127.0.0.1:8008/_synapse/admin/v2/users/@foo:bar.com', headers=headers)

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