Getting Started Using the Admin 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.

EMS (or ESS when using matrix-authentication-service)

See the MAS documentation for "Get an access token".

In short: the simplest way of fetching a (temporary) access token is by using the script device-code-grant.sh and running it locally (or on any Linux machine). When run, the script will prompt the user to open a link in their browser and authenticate with the homeserver, once completed the script will output an access token that can be used.

The script needs to be given the client URL, as used by the admin API requests below.

An example run looks like the following (the exact output may vary):

$ bash device-code-grant.sh https://matrix-client.matrix.org urn:matrix:org.matrix.msc2967.client:api:* urn:synapse:admin:*


Discovering the homeserver endpoints
>  GET https://matrix-client.matrix.org/_matrix/client/unstable/org.matrix.msc2965/auth_metadata
Registering the client
> POST https://account.matrix.org/oauth2/registration
> POST https://account.matrix.org/oauth2/device
-----------------------
            Homeserver: https://matrix-client.matrix.org
 Registration endpoint: https://account.matrix.org/oauth2/registration
  Device auth endpoint: https://account.matrix.org/oauth2/device
        Token endpoint: https://account.matrix.org/oauth2/token
             Client ID: AAAAAAAAAAAAAAAAAAAAAAAAAA
                 Scope: urn:synapse:admin:*
-----------------------

Open the following URL in your browser:
https://account.matrix.org/link?code=ABCDEF

Alternatively, go to https://account.matrix.org/link and enter the code ABCDEF

-----------------------

The script will then pause and wait for you to open the link and complete authentication in the web UI. Once complete the script will continue (potentially after a few seconds), displaying the access token:

> POST https://account.matrix.org/oauth2/token
Waiting for authorization
> POST https://account.matrix.org/oauth2/token
Waiting for authorization
> POST https://account.matrix.org/oauth2/token
Waiting for authorization
> POST https://account.matrix.org/oauth2/token
{
  "access_token": "mat_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA_aaaaaaa",
  "token_type": "Bearer",
  "expires_in": 14400,
  "scope": "urn:synapse:admin:*"
}

The admin token is mat_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA_aaaaaaa, which expires in 14400 seconds (or 4 hours)

ESS without matrix-authentication-service

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.