2341032cf2
* Admin API request explanation improved Pointed out, that the Admin API is not accessible by default from any remote computer, but only from the PC `matrix-synapse` is running on. Added a full, working example, making sure to include the cURL flag `-X`, which needs to be prepended to `GET`, `POST`, `PUT` etc. and listing the full query string including protocol, IP address and port. * Admin API request explanation improved * Apply suggestions from code review Update changelog. Reword prose. Co-authored-by: David Robertson <david.m.robertson1@gmail.com> |
||
|---|---|---|
| .. | ||
| background_updates.md | ||
| federation.md | ||
| README.md | ||
| registration_tokens.md | ||
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.)
A user can be marked as a server admin by updating the database directly, e.g.:
UPDATE users SET admin = 1 WHERE name = '@foo:bar.com';
A new server admin user can also be created using the register_new_matrix_user
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
Synapse's client listener is listening
on (e.g. 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.