synapse/docs/usage/administration/admin_api
jejo86 2341032cf2
Document advising against publicly exposing the Admin API and provide a usage example (#13231)
* 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>
2022-07-13 19:33:33 +01:00
..
background_updates.md Add an admin API to run background jobs. (#11352) 2021-11-19 19:39:46 +00:00
federation.md Add admin API to get a list of federated rooms (#11658) 2022-01-25 16:11:40 +00:00
README.md Document advising against publicly exposing the Admin API and provide a usage example (#13231) 2022-07-13 19:33:33 +01:00
registration_tokens.md Update doc of the allowed characters for registration tokens (#11093) 2021-10-15 09:56:39 +00:00

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.