forked-synapse/docs/usage/administration/admin_api
devonh 0fd6b269d3
Fix various typos in docs (#17114)
### Pull Request Checklist

<!-- Please read
https://element-hq.github.io/synapse/latest/development/contributing_guide.html
before submitting your pull request -->

* [X] Pull request is based on the develop branch
* [X] Pull request includes a [changelog
file](https://element-hq.github.io/synapse/latest/development/contributing_guide.html#changelog).
The entry should:
- Be a short description of your change which makes sense to users.
"Fixed a bug that prevented receiving messages from other servers."
instead of "Moved X method from `EventStore` to `EventWorkerStore`.".
  - Use markdown where necessary, mostly for `code blocks`.
  - End with either a period (.) or an exclamation mark (!).
  - Start with a capital letter.
- Feel free to credit yourself, by adding a sentence "Contributed by
@github_username." or "Contributed by [Your Name]." to the end of the
entry.
* [X] [Code
style](https://element-hq.github.io/synapse/latest/code_style.html) is
correct
(run the
[linters](https://element-hq.github.io/synapse/latest/development/contributing_guide.html#run-the-linters))
2024-04-26 18:10:45 +00:00
..
background_updates.md Fix various typos in docs (#17114) 2024-04-26 18:10:45 +00:00
federation.md Fix-up incorrect spellings in docs. (#16282) 2023-09-08 09:47:36 -04:00
README.md Fix broken links in the Synapse documentation. (#14744) 2023-01-05 18:18:00 +00:00
registration_tokens.md Add warnings about MSC3861 on certain APIs. (#16168) 2023-08-25 07:25:34 -04: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.)

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