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/<user_id>`pull/7649/head
parent
a0d2d81cf9
commit
1bc00fd76d
|
@ -0,0 +1 @@
|
||||||
|
Clarifications to the admin api documentation.
|
|
@ -4,17 +4,21 @@ Admin APIs
|
||||||
This directory includes documentation for the various synapse specific admin
|
This directory includes documentation for the various synapse specific admin
|
||||||
APIs available.
|
APIs available.
|
||||||
|
|
||||||
Only users that are server admins can use these APIs. A user can be marked as a
|
Authenticating as a server admin
|
||||||
server admin by updating the database directly, e.g.:
|
--------------------------------
|
||||||
|
|
||||||
``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.
|
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:
|
Once you have your `access_token`, to include it in a request, the best option is to add the token to a request header:
|
||||||
|
|
|
@ -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
|
users out of the group so that their clients will correctly handle the group
|
||||||
being deleted.
|
being deleted.
|
||||||
|
|
||||||
|
|
||||||
The API is:
|
The API is:
|
||||||
|
|
||||||
```
|
```
|
||||||
POST /_synapse/admin/v1/delete_group/<group_id>
|
POST /_synapse/admin/v1/delete_group/<group_id>
|
||||||
```
|
```
|
||||||
|
|
||||||
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).
|
||||||
|
|
|
@ -6,9 +6,10 @@ The API is:
|
||||||
```
|
```
|
||||||
GET /_synapse/admin/v1/room/<room_id>/media
|
GET /_synapse/admin/v1/room/<room_id>/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": [
|
"local": [
|
||||||
|
@ -99,4 +100,3 @@ Response:
|
||||||
"num_quarantined": 10 # The number of media items successfully quarantined
|
"num_quarantined": 10 # The number of media items successfully quarantined
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
|
@ -15,7 +15,8 @@ The API is:
|
||||||
|
|
||||||
``POST /_synapse/admin/v1/purge_history/<room_id>[/<event_id>]``
|
``POST /_synapse/admin/v1/purge_history/<room_id>[/<event_id>]``
|
||||||
|
|
||||||
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>`_.
|
||||||
|
|
||||||
By default, events sent by local users are not deleted, as they may represent
|
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
|
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/<purge_id>``
|
``GET /_synapse/admin/v1/purge_history_status/<purge_id>``
|
||||||
|
|
||||||
(again, with a suitable ``access_token``). This API returns a JSON body like
|
Again, you will need to authenticate by providing an ``access_token`` for a
|
||||||
the following:
|
server admin.
|
||||||
|
|
||||||
|
This API returns a JSON body like the following:
|
||||||
|
|
||||||
.. code:: json
|
.. code:: json
|
||||||
|
|
||||||
|
|
|
@ -6,12 +6,15 @@ media.
|
||||||
|
|
||||||
The API is::
|
The API is::
|
||||||
|
|
||||||
POST /_synapse/admin/v1/purge_media_cache?before_ts=<unix_timestamp_in_ms>&access_token=<access_token>
|
POST /_synapse/admin/v1/purge_media_cache?before_ts=<unix_timestamp_in_ms>
|
||||||
|
|
||||||
{}
|
{}
|
||||||
|
|
||||||
Which will remove all cached media that was last accessed before
|
\... which will remove all cached media that was last accessed before
|
||||||
``<unix_timestamp_in_ms>``.
|
``<unix_timestamp_in_ms>``.
|
||||||
|
|
||||||
|
To use it, you will need to authenticate by providing an ``access_token`` for a
|
||||||
|
server admin: see `README.rst <README.rst>`_.
|
||||||
|
|
||||||
If the user re-requests purged remote media, synapse will re-request the media
|
If the user re-requests purged remote media, synapse will re-request the media
|
||||||
from the originating server.
|
from the originating server.
|
||||||
|
|
|
@ -23,7 +23,8 @@ POST /_synapse/admin/v1/join/<room_id_or_alias>
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
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:
|
Response:
|
||||||
|
|
||||||
|
|
|
@ -1,11 +1,47 @@
|
||||||
.. contents::
|
.. contents::
|
||||||
|
|
||||||
|
Query User Account
|
||||||
|
==================
|
||||||
|
|
||||||
|
This API returns information about a specific user account.
|
||||||
|
|
||||||
|
The api is::
|
||||||
|
|
||||||
|
GET /_synapse/admin/v2/users/<user_id>
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
.. code:: json
|
||||||
|
|
||||||
|
{
|
||||||
|
"displayname": "User",
|
||||||
|
"threepids": [
|
||||||
|
{
|
||||||
|
"medium": "email",
|
||||||
|
"address": "<user_mail_1>"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"medium": "email",
|
||||||
|
"address": "<user_mail_2>"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"avatar_url": "<avatar_url>",
|
||||||
|
"admin": false,
|
||||||
|
"deactivated": false
|
||||||
|
}
|
||||||
|
|
||||||
|
URL parameters:
|
||||||
|
|
||||||
|
- ``user_id``: fully-qualified user id: for example, ``@user:server.com``.
|
||||||
|
|
||||||
Create or modify Account
|
Create or modify Account
|
||||||
========================
|
========================
|
||||||
|
|
||||||
This API allows an administrator to create or modify a user account with a
|
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,
|
specific ``user_id``.
|
||||||
``@user:server.com``.
|
|
||||||
|
|
||||||
This api is::
|
This api is::
|
||||||
|
|
||||||
|
@ -33,19 +69,24 @@ with a body of:
|
||||||
"deactivated": false
|
"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 <README.rst>`_.
|
||||||
|
|
||||||
Parameters:
|
URL parameters:
|
||||||
|
|
||||||
|
- ``user_id``: fully-qualified user id: for example, ``@user:server.com``.
|
||||||
|
|
||||||
|
Body parameters:
|
||||||
|
|
||||||
- ``password``, optional. If provided, the user's password is updated and all
|
- ``password``, optional. If provided, the user's password is updated and all
|
||||||
devices are logged out.
|
devices are logged out.
|
||||||
|
|
||||||
- ``displayname``, optional, defaults to the value of ``user_id``.
|
- ``displayname``, optional, defaults to the value of ``user_id``.
|
||||||
|
|
||||||
- ``threepids``, optional, allows setting the third-party IDs (email, msisdn)
|
- ``threepids``, optional, allows setting the third-party IDs (email, msisdn)
|
||||||
belonging to a user.
|
belonging to a user.
|
||||||
|
|
||||||
- ``avatar_url``, optional, must be a
|
- ``avatar_url``, optional, must be a
|
||||||
`MXC URI <https://matrix.org/docs/spec/client_server/r0.6.0#matrix-content-mxc-uris>`_.
|
`MXC URI <https://matrix.org/docs/spec/client_server/r0.6.0#matrix-content-mxc-uris>`_.
|
||||||
|
|
||||||
- ``admin``, optional, defaults to ``false``.
|
- ``admin``, optional, defaults to ``false``.
|
||||||
|
@ -63,7 +104,8 @@ The api is::
|
||||||
|
|
||||||
GET /_synapse/admin/v2/users?from=0&limit=10&guests=false
|
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 <README.rst>`_.
|
||||||
|
|
||||||
The parameter ``from`` is optional but used for pagination, denoting the
|
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
|
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
|
If the endpoint does not return a ``next_token`` then there are no more users
|
||||||
to paginate through.
|
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::
|
The api is::
|
||||||
|
|
||||||
GET /_synapse/admin/v1/whois/<user_id> (deprecated)
|
GET /_synapse/admin/v1/whois/<user_id>
|
||||||
GET /_synapse/admin/v2/users/<user_id>
|
|
||||||
|
|
||||||
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:
|
It returns a JSON body like the following:
|
||||||
|
|
||||||
|
@ -181,9 +223,10 @@ with a body of:
|
||||||
"erase": true
|
"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 <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.
|
An empty body may be passed for backwards compatibility.
|
||||||
|
|
||||||
|
|
||||||
|
@ -205,7 +248,8 @@ with a body of:
|
||||||
"logout_devices": true,
|
"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 <README.rst>`_.
|
||||||
|
|
||||||
The parameter ``new_password`` is required.
|
The parameter ``new_password`` is required.
|
||||||
The parameter ``logout_devices`` is optional and defaults to ``true``.
|
The parameter ``logout_devices`` is optional and defaults to ``true``.
|
||||||
|
@ -218,7 +262,8 @@ The api is::
|
||||||
|
|
||||||
GET /_synapse/admin/v1/users/<user_id>/admin
|
GET /_synapse/admin/v1/users/<user_id>/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 <README.rst>`_.
|
||||||
|
|
||||||
A response body like the following is returned:
|
A response body like the following is returned:
|
||||||
|
|
||||||
|
@ -246,7 +291,8 @@ with a body of:
|
||||||
"admin": true
|
"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 <README.rst>`_.
|
||||||
|
|
||||||
|
|
||||||
User devices
|
User devices
|
||||||
|
@ -256,17 +302,14 @@ List all devices
|
||||||
----------------
|
----------------
|
||||||
Gets information about all devices for a specific ``user_id``.
|
Gets information about all devices for a specific ``user_id``.
|
||||||
|
|
||||||
**Usage**
|
The API is::
|
||||||
|
|
||||||
A standard request to query the devices of an user:
|
GET /_synapse/admin/v2/users/<user_id>/devices
|
||||||
|
|
||||||
::
|
To use it, you will need to authenticate by providing an ``access_token`` for a
|
||||||
|
server admin: see `README.rst <README.rst>`_.
|
||||||
|
|
||||||
GET /_synapse/admin/v2/users/<user_id>/devices
|
A response body like the following is returned:
|
||||||
|
|
||||||
{}
|
|
||||||
|
|
||||||
Response:
|
|
||||||
|
|
||||||
.. code:: json
|
.. code:: json
|
||||||
|
|
||||||
|
@ -291,11 +334,13 @@ Response:
|
||||||
|
|
||||||
**Parameters**
|
**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``.
|
- ``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.
|
- ``devices`` - An array of objects, each containing information about a device.
|
||||||
Device objects contain the following fields:
|
Device objects contain the following fields:
|
||||||
|
@ -314,11 +359,7 @@ Delete multiple devices
|
||||||
Deletes the given devices for a specific ``user_id``, and invalidates
|
Deletes the given devices for a specific ``user_id``, and invalidates
|
||||||
any access token associated with them.
|
any access token associated with them.
|
||||||
|
|
||||||
**Usage**
|
The API is::
|
||||||
|
|
||||||
A standard request to delete devices:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
POST /_synapse/admin/v2/users/<user_id>/delete_devices
|
POST /_synapse/admin/v2/users/<user_id>/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 <README.rst>`_.
|
||||||
|
|
||||||
Response:
|
An empty JSON dict is returned.
|
||||||
|
|
||||||
.. code:: json
|
|
||||||
|
|
||||||
{}
|
|
||||||
|
|
||||||
**Parameters**
|
**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``.
|
- ``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``.
|
Gets information on a single device, by ``device_id`` for a specific ``user_id``.
|
||||||
|
|
||||||
**Usage**
|
The API is::
|
||||||
|
|
||||||
A standard request to get a device:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
GET /_synapse/admin/v2/users/<user_id>/devices/<device_id>
|
GET /_synapse/admin/v2/users/<user_id>/devices/<device_id>
|
||||||
|
|
||||||
{}
|
To use it, you will need to authenticate by providing an ``access_token`` for a
|
||||||
|
server admin: see `README.rst <README.rst>`_.
|
||||||
|
|
||||||
|
A response body like the following is returned:
|
||||||
Response:
|
|
||||||
|
|
||||||
.. code:: json
|
.. code:: json
|
||||||
|
|
||||||
|
@ -375,12 +410,14 @@ Response:
|
||||||
|
|
||||||
**Parameters**
|
**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``.
|
- ``user_id`` - fully qualified: for example, ``@user:server.com``.
|
||||||
- ``device_id`` - The device to retrieve.
|
- ``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.
|
- ``device_id`` - Identifier of device.
|
||||||
- ``display_name`` - Display name set by the user for this 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``.
|
Updates the metadata on the given ``device_id`` for a specific ``user_id``.
|
||||||
|
|
||||||
**Usage**
|
The API is::
|
||||||
|
|
||||||
A standard request to update a device:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
PUT /_synapse/admin/v2/users/<user_id>/devices/<device_id>
|
PUT /_synapse/admin/v2/users/<user_id>/devices/<device_id>
|
||||||
|
|
||||||
|
@ -407,16 +440,14 @@ A standard request to update a device:
|
||||||
"display_name": "My other phone"
|
"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 <README.rst>`_.
|
||||||
|
|
||||||
Response:
|
An empty JSON dict is returned.
|
||||||
|
|
||||||
.. code:: json
|
|
||||||
|
|
||||||
{}
|
|
||||||
|
|
||||||
**Parameters**
|
**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``.
|
- ``user_id`` - fully qualified: for example, ``@user:server.com``.
|
||||||
- ``device_id`` - The device to update.
|
- ``device_id`` - The device to update.
|
||||||
|
@ -431,26 +462,20 @@ Delete a device
|
||||||
Deletes the given ``device_id`` for a specific ``user_id``,
|
Deletes the given ``device_id`` for a specific ``user_id``,
|
||||||
and invalidates any access token associated with it.
|
and invalidates any access token associated with it.
|
||||||
|
|
||||||
**Usage**
|
The API is::
|
||||||
|
|
||||||
A standard request for delete a device:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
DELETE /_synapse/admin/v2/users/<user_id>/devices/<device_id>
|
DELETE /_synapse/admin/v2/users/<user_id>/devices/<device_id>
|
||||||
|
|
||||||
{}
|
{}
|
||||||
|
|
||||||
|
To use it, you will need to authenticate by providing an ``access_token`` for a
|
||||||
|
server admin: see `README.rst <README.rst>`_.
|
||||||
|
|
||||||
Response:
|
An empty JSON dict is returned.
|
||||||
|
|
||||||
.. code:: json
|
|
||||||
|
|
||||||
{}
|
|
||||||
|
|
||||||
**Parameters**
|
**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``.
|
- ``user_id`` - fully qualified: for example, ``@user:server.com``.
|
||||||
- ``device_id`` - The device to delete.
|
- ``device_id`` - The device to delete.
|
||||||
|
|
Loading…
Reference in New Issue