diff options
| author | timaeos <104638316+timaeos@users.noreply.github.com> | 2022-08-13 13:25:39 -0500 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2022-08-13 20:25:39 +0200 |
| commit | da7d209b10c01ea3762bf5e524dcc17549de934d (patch) | |
| tree | 266dbe941679e96a12b6283283de4c08089fe9d6 | |
| parent | 30dbc5ac448e30f69305c81b7049d6bd30ae76d0 (diff) | |
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>
| -rw-r--r-- | docs/administration/4_adminapi.md | 46 |
1 files changed, 46 insertions, 0 deletions
diff --git a/docs/administration/4_adminapi.md b/docs/administration/4_adminapi.md index 783fee95..a34bfde1 100644 --- a/docs/administration/4_adminapi.md +++ b/docs/administration/4_adminapi.md @@ -13,6 +13,25 @@ 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` @@ -38,7 +57,34 @@ Request body format: 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](https://spec.matrix.org/v1.3/client-server-api/#server-notices) 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](createusers) for guidance on configuring and using this endpoint. + +## GET `/_matrix/client/v3/admin/whois/{userId}` + +From the [Matrix Spec](https://spec.matrix.org/v1.3/client-server-api/#get_matrixclientv3adminwhoisuserid). +Gets information about a particular user. `userId` is the full user ID (e.g. `@alice:domain.com`) |