668597214f
* Improved section regarding server admin Added steps describing how to elevate an existing user to administrator by manipulating a `postgres` database. Signed-off-by: jejo86 28619134+jejo86@users.noreply.github.com * Improved section regarding server admin * Reference database settings Add instructions to check database settings to find out the database name, instead of listing all available PostgreSQL databases. * Add suggestions from PR conversation Replace config filename `homeserver.yaml`. with "config file". Remove instructions to switch to `postgres` user. Add instructions how to connect to SQLite database. * Update changelog.d/13230.doc Co-authored-by: reivilibre <olivier@librepush.net> |
||
|---|---|---|
| .. | ||
| README.md | ||
| background_updates.md | ||
| federation.md | ||
| registration_tokens.md | ||
README.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.)
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.