From 1bc00fd76d1741477ff8ae4f2cc68102d483014c Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Fri, 5 Jun 2020 17:31:05 +0100 Subject: Clarifications to the admin api documentation (#7647) * Clarify how to authenticate * path params are not the same thing as query params * Fix documentation for `/_synapse/admin/v2/users/` --- docs/admin_api/README.rst | 18 ++-- docs/admin_api/delete_group.md | 4 +- docs/admin_api/media_admin_api.md | 6 +- docs/admin_api/purge_history_api.rst | 9 +- docs/admin_api/purge_remote_media.rst | 7 +- docs/admin_api/room_membership.md | 3 +- docs/admin_api/user_admin_api.rst | 167 +++++++++++++++++++--------------- 7 files changed, 125 insertions(+), 89 deletions(-) (limited to 'docs/admin_api') diff --git a/docs/admin_api/README.rst b/docs/admin_api/README.rst index 191806c5b4..9587bee0ce 100644 --- a/docs/admin_api/README.rst +++ b/docs/admin_api/README.rst @@ -4,17 +4,21 @@ Admin APIs This directory includes documentation for the various synapse specific admin APIs available. -Only users that are server admins can use these APIs. A user can be marked as a -server admin by updating the database directly, e.g.: +Authenticating as a server admin +-------------------------------- -``UPDATE users SET admin = 1 WHERE name = '@foo:bar.com'`` +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.) -Restarting may be required for the changes to register. +A user can be marked as a server admin by updating the database directly, e.g.: -Using an admin access_token -########################### +.. code-block:: sql + + 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`` script. -Many of the API calls listed in the documentation here will require to include an admin `access_token`. Finding your user's `access_token` is client-dependent, but will usually be shown in the client's settings. Once you have your `access_token`, to include it in a request, the best option is to add the token to a request header: diff --git a/docs/admin_api/delete_group.md b/docs/admin_api/delete_group.md index 1710488ea8..c061678e75 100644 --- a/docs/admin_api/delete_group.md +++ b/docs/admin_api/delete_group.md @@ -4,11 +4,11 @@ This API lets a server admin delete a local group. Doing so will kick all users out of the group so that their clients will correctly handle the group being deleted. - The API is: ``` POST /_synapse/admin/v1/delete_group/ ``` -including an `access_token` of a server admin. +To use it, you will need to authenticate by providing an `access_token` for a +server admin: see [README.rst](README.rst). diff --git a/docs/admin_api/media_admin_api.md b/docs/admin_api/media_admin_api.md index 46ba7a1a71..26948770d8 100644 --- a/docs/admin_api/media_admin_api.md +++ b/docs/admin_api/media_admin_api.md @@ -6,9 +6,10 @@ The API is: ``` GET /_synapse/admin/v1/room//media ``` -including an `access_token` of a server admin. +To use it, you will need to authenticate by providing an `access_token` for a +server admin: see [README.rst](README.rst). -It returns a JSON body like the following: +The API returns a JSON body like the following: ``` { "local": [ @@ -99,4 +100,3 @@ Response: "num_quarantined": 10 # The number of media items successfully quarantined } ``` - diff --git a/docs/admin_api/purge_history_api.rst b/docs/admin_api/purge_history_api.rst index e2a620c54f..92cd05f2a0 100644 --- a/docs/admin_api/purge_history_api.rst +++ b/docs/admin_api/purge_history_api.rst @@ -15,7 +15,8 @@ The API is: ``POST /_synapse/admin/v1/purge_history/[/]`` -including an ``access_token`` of a server admin. +To use it, you will need to authenticate by providing an ``access_token`` for a +server admin: see `README.rst `_. By default, events sent by local users are not deleted, as they may represent the only copies of this content in existence. (Events sent by remote users are @@ -54,8 +55,10 @@ It is possible to poll for updates on recent purges with a second API; ``GET /_synapse/admin/v1/purge_history_status/`` -(again, with a suitable ``access_token``). This API returns a JSON body like -the following: +Again, you will need to authenticate by providing an ``access_token`` for a +server admin. + +This API returns a JSON body like the following: .. code:: json diff --git a/docs/admin_api/purge_remote_media.rst b/docs/admin_api/purge_remote_media.rst index dacd5bc8fb..00cb6b0589 100644 --- a/docs/admin_api/purge_remote_media.rst +++ b/docs/admin_api/purge_remote_media.rst @@ -6,12 +6,15 @@ media. The API is:: - POST /_synapse/admin/v1/purge_media_cache?before_ts=&access_token= + POST /_synapse/admin/v1/purge_media_cache?before_ts= {} -Which will remove all cached media that was last accessed before +\... which will remove all cached media that was last accessed before ````. +To use it, you will need to authenticate by providing an ``access_token`` for a +server admin: see `README.rst `_. + If the user re-requests purged remote media, synapse will re-request the media from the originating server. diff --git a/docs/admin_api/room_membership.md b/docs/admin_api/room_membership.md index 16736d3d37..b6746ff5e4 100644 --- a/docs/admin_api/room_membership.md +++ b/docs/admin_api/room_membership.md @@ -23,7 +23,8 @@ POST /_synapse/admin/v1/join/ } ``` -Including an `access_token` of a server admin. +To use it, you will need to authenticate by providing an `access_token` for a +server admin: see [README.rst](README.rst). Response: diff --git a/docs/admin_api/user_admin_api.rst b/docs/admin_api/user_admin_api.rst index a3d52b282b..7b030a6285 100644 --- a/docs/admin_api/user_admin_api.rst +++ b/docs/admin_api/user_admin_api.rst @@ -1,11 +1,47 @@ .. contents:: +Query User Account +================== + +This API returns information about a specific user account. + +The api is:: + + GET /_synapse/admin/v2/users/ + +To use it, you will need to authenticate by providing an ``access_token`` for a +server admin: see `README.rst `_. + +It returns a JSON body like the following: + +.. code:: json + + { + "displayname": "User", + "threepids": [ + { + "medium": "email", + "address": "" + }, + { + "medium": "email", + "address": "" + } + ], + "avatar_url": "", + "admin": false, + "deactivated": false + } + +URL parameters: + +- ``user_id``: fully-qualified user id: for example, ``@user:server.com``. + Create or modify Account ======================== This API allows an administrator to create or modify a user account with a -specific ``user_id``. Be aware that ``user_id`` is fully qualified: for example, -``@user:server.com``. +specific ``user_id``. This api is:: @@ -33,19 +69,24 @@ with a body of: "deactivated": false } -including an ``access_token`` of a server admin. +To use it, you will need to authenticate by providing an ``access_token`` for a +server admin: see `README.rst `_. + +URL parameters: + +- ``user_id``: fully-qualified user id: for example, ``@user:server.com``. -Parameters: +Body parameters: - ``password``, optional. If provided, the user's password is updated and all devices are logged out. - + - ``displayname``, optional, defaults to the value of ``user_id``. - ``threepids``, optional, allows setting the third-party IDs (email, msisdn) belonging to a user. -- ``avatar_url``, optional, must be a +- ``avatar_url``, optional, must be a `MXC URI `_. - ``admin``, optional, defaults to ``false``. @@ -63,7 +104,8 @@ The api is:: GET /_synapse/admin/v2/users?from=0&limit=10&guests=false -including an ``access_token`` of a server admin. +To use it, you will need to authenticate by providing an `access_token` for a +server admin: see `README.rst `_. The parameter ``from`` is optional but used for pagination, denoting the offset in the returned results. This should be treated as an opaque value and @@ -118,17 +160,17 @@ with ``from`` set to the value of ``next_token``. This will return a new page. If the endpoint does not return a ``next_token`` then there are no more users to paginate through. -Query Account -============= +Query current sessions for a user +================================= -This API returns information about a specific user account. +This API returns information about the active sessions for a specific user. The api is:: - GET /_synapse/admin/v1/whois/ (deprecated) - GET /_synapse/admin/v2/users/ + GET /_synapse/admin/v1/whois/ -including an ``access_token`` of a server admin. +To use it, you will need to authenticate by providing an ``access_token`` for a +server admin: see `README.rst `_. It returns a JSON body like the following: @@ -181,9 +223,10 @@ with a body of: "erase": true } -including an ``access_token`` of a server admin. +To use it, you will need to authenticate by providing an ``access_token`` for a +server admin: see `README.rst `_. -The erase parameter is optional and defaults to 'false'. +The erase parameter is optional and defaults to ``false``. An empty body may be passed for backwards compatibility. @@ -205,7 +248,8 @@ with a body of: "logout_devices": true, } -including an ``access_token`` of a server admin. +To use it, you will need to authenticate by providing an ``access_token`` for a +server admin: see `README.rst `_. The parameter ``new_password`` is required. The parameter ``logout_devices`` is optional and defaults to ``true``. @@ -218,7 +262,8 @@ The api is:: GET /_synapse/admin/v1/users//admin -including an ``access_token`` of a server admin. +To use it, you will need to authenticate by providing an ``access_token`` for a +server admin: see `README.rst `_. A response body like the following is returned: @@ -246,7 +291,8 @@ with a body of: "admin": true } -including an ``access_token`` of a server admin. +To use it, you will need to authenticate by providing an ``access_token`` for a +server admin: see `README.rst `_. User devices @@ -256,17 +302,14 @@ List all devices ---------------- Gets information about all devices for a specific ``user_id``. -**Usage** - -A standard request to query the devices of an user: +The API is:: -:: + GET /_synapse/admin/v2/users//devices - GET /_synapse/admin/v2/users//devices +To use it, you will need to authenticate by providing an ``access_token`` for a +server admin: see `README.rst `_. - {} - -Response: +A response body like the following is returned: .. code:: json @@ -291,11 +334,13 @@ Response: **Parameters** -The following query parameters are available: +The following parameters should be set in the URL: - ``user_id`` - fully qualified: for example, ``@user:server.com``. -The following fields are possible in the JSON response body: +**Response** + +The following fields are returned in the JSON response body: - ``devices`` - An array of objects, each containing information about a device. Device objects contain the following fields: @@ -314,11 +359,7 @@ Delete multiple devices Deletes the given devices for a specific ``user_id``, and invalidates any access token associated with them. -**Usage** - -A standard request to delete devices: - -:: +The API is:: POST /_synapse/admin/v2/users//delete_devices @@ -329,16 +370,14 @@ A standard request to delete devices: ], } +To use it, you will need to authenticate by providing an ``access_token`` for a +server admin: see `README.rst `_. -Response: - -.. code:: json - - {} +An empty JSON dict is returned. **Parameters** -The following query parameters are available: +The following parameters should be set in the URL: - ``user_id`` - fully qualified: for example, ``@user:server.com``. @@ -350,18 +389,14 @@ Show a device --------------- Gets information on a single device, by ``device_id`` for a specific ``user_id``. -**Usage** - -A standard request to get a device: - -:: +The API is:: GET /_synapse/admin/v2/users//devices/ - {} - +To use it, you will need to authenticate by providing an ``access_token`` for a +server admin: see `README.rst `_. -Response: +A response body like the following is returned: .. code:: json @@ -375,12 +410,14 @@ Response: **Parameters** -The following query parameters are available: +The following parameters should be set in the URL: - ``user_id`` - fully qualified: for example, ``@user:server.com``. - ``device_id`` - The device to retrieve. -The following fields are possible in the JSON response body: +**Response** + +The following fields are returned in the JSON response body: - ``device_id`` - Identifier of device. - ``display_name`` - Display name set by the user for this device. @@ -395,11 +432,7 @@ Update a device --------------- Updates the metadata on the given ``device_id`` for a specific ``user_id``. -**Usage** - -A standard request to update a device: - -:: +The API is:: PUT /_synapse/admin/v2/users//devices/ @@ -407,16 +440,14 @@ A standard request to update a device: "display_name": "My other phone" } +To use it, you will need to authenticate by providing an ``access_token`` for a +server admin: see `README.rst `_. -Response: - -.. code:: json - - {} +An empty JSON dict is returned. **Parameters** -The following query parameters are available: +The following parameters should be set in the URL: - ``user_id`` - fully qualified: for example, ``@user:server.com``. - ``device_id`` - The device to update. @@ -431,26 +462,20 @@ Delete a device Deletes the given ``device_id`` for a specific ``user_id``, and invalidates any access token associated with it. -**Usage** - -A standard request for delete a device: - -:: +The API is:: DELETE /_synapse/admin/v2/users//devices/ {} +To use it, you will need to authenticate by providing an ``access_token`` for a +server admin: see `README.rst `_. -Response: - -.. code:: json - - {} +An empty JSON dict is returned. **Parameters** -The following query parameters are available: +The following parameters should be set in the URL: - ``user_id`` - fully qualified: for example, ``@user:server.com``. - ``device_id`` - The device to delete. -- cgit 1.4.1