The Admin API
Authenticate as a server admin
Many of the API calls in the admin api will require an
access_token for a
server admin. (Note that a server admin is distinct from a room admin.)
An existing user can be marked as a server admin by updating the database directly.
Check your database settings in the configuration file, connect to the correct database using either
psql [database name] (if using PostgreSQL) or
sqlite3 path/to/your/database.db (if using SQLite) and elevate the user
@foo:bar.com to administrator.
UPDATE users SET admin = 1 WHERE name = '@foo:bar.com';
A new server admin user can also be created using the
command. This is a script that is distributed as part of synapse. It is possibly
already on your
$PATH depending on how Synapse was installed.
Finding your user's
access_token is client-dependent, but will usually be shown in the client's settings.
Making an Admin API request
For security reasons, we recommend
that the Admin API (
/_synapse/admin/...) should be hidden from public view using a
reverse proxy. This means you should typically query the Admin API from a terminal on
the machine which runs Synapse.
Once you have your
access_token, 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:
curl --header "Authorization: Bearer <access_token>" <the_rest_of_your_API_request>
For example, suppose we want to
query the account of the user
@foo:bar.com. We need an admin access token (e.g.
syt_AjfVef2_L33JNpafeif_0feKJfeaf0CQpoZk), and we need to know which port
client listener is listening
8008). Then we can use the following command to request the account
information from the Admin API.
curl --header "Authorization: Bearer syt_AjfVef2_L33JNpafeif_0feKJfeaf0CQpoZk" -X GET http://127.0.0.1:8008/_synapse/admin/v2/users/@foo:bar.com
For more details on access tokens in Matrix, please refer to the complete matrix spec documentation.