dendrite/docs/administration/4_adminapi.md
timaeos da7d209b10
Admin endpoint documentation (#2640)
* Adding documentation for administration end points that aren't currently documented

* Additional information on using the administration API

* Fix inaccurate information on server notice documentation

* Fix typo in the curl command

* Add details about using the whois endpoint

* fix formatting in documentation for admin whois endpoint

* Fix more documentation formatting

* Additional formatting updates to match other formats

* Add a link to the server notice information in the Matrix Spec

* Fix broken link on server notices

* Adding access token information and admin info

* adding a warning regarding access_token

Co-authored-by: Timothy Arnold <Yourmove@gmail.com>
2022-08-13 20:25:39 +02:00

2.9 KiB

title parent permalink
Supported admin APIs Administration /administration/adminapi

Supported admin APIs

Dendrite supports, at present, a very small number of endpoints that allow admin users to perform administrative functions. Please note that there is no API stability guarantee on these endpoints at present — they may change shape without warning.

More endpoints will be added in the future.

Endpoints may be used directly through curl:

curl --header "Authorization: Bearer <access_token>" -X <POST|GET|PUT> <Endpoint URI> -d '<Request Body Contents>'

An access_token can be obtained through most Element-based matrix clients by going to Settings -> Help & About -> Advanced -> Access Token. Be aware that an access_token allows a client to perform actions as an user and should be kept secret.

The user must be an administrator in the account_accounts table in order to use these endpoints.

Existing user accounts can be set to administrative accounts by changing account_type to 3 in account_accounts

UPDATE account_accounts SET account_type = 3 WHERE localpart = '$localpart';

Where $localpart is the username only (e.g. alice).

GET /_dendrite/admin/evacuateRoom/{roomID}

This endpoint will instruct Dendrite to part all local users from the given roomID in the URL. It may take some time to complete. A JSON body will be returned containing the user IDs of all affected users.

GET /_dendrite/admin/evacuateUser/{userID}

This endpoint will instruct Dendrite to part the given local userID in the URL from all rooms which they are currently joined. A JSON body will be returned containing the room IDs of all affected rooms.

POST /_dendrite/admin/resetPassword/{localpart}

Request body format:

{
    "password": "new_password_here"
}

Reset the password of a local user. The localpart is the username only, i.e. if the full user ID is @alice:domain.com then the local part is alice.

POST /_synapse/admin/v1/send_server_notice

Request body format:

{
    "user_id": "@target_user:server_name",
    "content": {
       "msgtype": "m.text",
       "body": "This is my message"
    }
}

Send a server notice to a specific user. See the Matrix Spec for additional details on server notice behaviour. If successfully sent, the API will return the following response:

{
     "event_id": "<event_id>"
}

GET /_synapse/admin/v1/register

Shared secret registration — please see the user creation page for guidance on configuring and using this endpoint.

GET /_matrix/client/v3/admin/whois/{userId}

From the Matrix Spec. Gets information about a particular user. userId is the full user ID (e.g. @alice:domain.com)