Advanced Administration

Documentation covering more advanced topics relating to the administration of your homeserver.

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

Getting Started Using the Client-Server API

The Client-Server API allows a user to perform any action they could via a Matrix client programatically. In order to make use of the API you will need to retrieve an access token for your account.

Getting your access_token

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

Using your preferred method, you will need to authenticate each request to a Client-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 https://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('https://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 Client-Server API documentation.

Using Python with the Admin + Client-Server APIs

You can use Python to make consume and utilise APIs, including those available with Matrix - such as the Synapse Admin API, and the Matrix Client-Server API. See the below docs to learn more about them before progressing with this guide.

The key requirement before progressing is getting the Matrix Accounts' access_token, if your using the Synapse Admin API, you must use a Matrix Account which is a Synapse Admin.

Using python

You will need Python setup on your system to make use of the script. The best way to use Python is to keep individual projects / scripts in separate virtual environments (venv). The documentation on this can be found here, for example on Windows you'd use:

python -m venv .\myPythonProject\
.\myPythonProject\Scripts\Activate.ps1

The script uses the requests library in order to make the API requests, to install in in you venv, after activating run:

python -m pip install requests

You will then be able to run scripts you create by using:

python .\myPythonProject\scriptName.py

Writing a python script

At it's most basic, you will need to setup the below template within your script:

import requests

homeseverURL = 'example.com'
accountToken = 'accountTokenStringExample'
requestHeaders = {
    'Authorization': 'Bearer ' + accountToken
}
requestData = {
    'key': 'value'
}

getResponse = requests.post('API Endpoint URL', headers=requestHeaders).json()
postResponse = requests.post('API Endpoint URL', headers=requestHeaders, data=requestData).json()

The below examples are for reference only, when running any scripts with any access to your homeserver you should verify and understand the script yourself, the below may end up out-dated so please use the various linked documentation before running. We do not provide any support for the following scripts.

Example #1: Join Users to Rooms

Let's say you wanted to join a list of users to a list of rooms, you would adapt this template to something like the below to make use of the Edit Room Membership API:

import requests

# Homeserver
homeserverURL = 'synapse.example.com'

# Credentials
accountToken = 'accountTokenStringExample'

# Rooms to Auto-Join
roomAliasList = ['#room1:example.com', '#room2:example.com']

# Users to Auto-Join
userList = ['@user1:example.com', '@user2:example.com']

# API Auth Header
requestHeaders = {
    'Authorization': 'Bearer ' + accountToken,
}

# Loop through all rooms
for roomAlias in roomAliasList:
    # Construct API Endpoint URL
    editRoomMembershipURL = 'https://' + homeserverURL + '/_synapse/admin/v1/join/' + roomAlias
    # Loop through all users
    for user in userList:
      	# Construct POST contents
        editRoomMembershipData = {
            "user_id": user
        }
        # Send Request
        response = requests.post(editRoomMembershipURL, headers=requestHeaders, data=editRoomMembershipData).json()
Example #2: Delete Older Media

If you are looking to remove all media older than a specific Unix Timestamp, you could adjust the template above to make use of Delete local media by date or size.

import requests

# Homeserver
homeserverURL = 'synapse.example.com'

# Credentials
accountToken = 'accountTokenStringExample'

# API Auth Header
requestHeaders = {
    'Authorization': 'Bearer ' + accountToken,
}

# Construct API Endpoint URL
unixTimestamp : str = '1672531200000'
deleteMediaURL = 'https://' + homeserverURL + '/_synapse/admin/v1/media/delete?before_ts=' + unixTimestamp

# Send Request
response = requests.post(deleteMediaURL, headers=requestHeaders).json()
Example #3: Remove specific external_ids

If you are looking to remove specific External IDs from user accounts, you can use the below. Simply replace the url, adminToken and authProvider variables at the top of the script with the desired values. This script makes use of List Accounts to get all users, Query User Account to get each users' external_ids and finally Create or Modify Account to remove that specific external_id.

import requests
import json

url = 'synapse.example.com' # Replace with Synapse FQDN
adminToken = 'exampleToken' # Replace with Admin Token
authProvider = 'exampleAuth'# Replace with Auth Provider to Delete

headers = {
    'Authorization': 'Bearer ' + adminToken,
}
userAccountURL = 'https://' + url + '/_synapse/admin/v2/users'

# GET ALL USER ACCOUNTS
def get_all_users():
    all_users = []
    list_account_from = 0
    users = requests.get(userAccountURL + '?limit=5', headers=headers).json()
    all_users.extend(users['users'])

    while 'next_token' in users.keys():
        list_account_from = int(users['next_token'])
        users = requests.get(userAccountURL + '?from=' + str(list_account_from), headers=headers).json()
        all_users.extend(users['users'])

    return all_users

# DELETE EXTERNAL ID WITH SPECIFIED AUTH PROVIDER
def delete_matching_external_id(auth_provider, user_accounts):
    for user in user_accounts:
        user_details = requests.get(userAccountURL + '/' + user['name'], headers=headers).json()
        if 'external_ids' in user_details.keys():
            body = {
                'external_ids': []
            }
            for external_id in user_details['external_ids']:
                if external_id['auth_provider'] != auth_provider:
                    body['external_ids'].append(external_id)
            body_json = json.dumps(body)
            result = requests.put(userAccountURL + '/' + user['name'], headers=headers, data=body_json).json()

delete_matching_external_id(authProvider, get_all_users())