mirror of
https://mau.dev/maunium/synapse.git
synced 2024-09-05 17:12:37 +00:00
Clean up admin api docs (#7361)
This commit is contained in:
parent
04dd7d182d
commit
c58ae367d8
1
changelog.d/7361.doc
Normal file
1
changelog.d/7361.doc
Normal file
@ -0,0 +1 @@
|
|||||||
|
Clarify endpoint usage in the users admin api documentation.
|
@ -33,12 +33,22 @@ with a body of:
|
|||||||
|
|
||||||
including an ``access_token`` of a server admin.
|
including an ``access_token`` of a server admin.
|
||||||
|
|
||||||
The parameter ``displayname`` is optional and defaults to ``user_id``.
|
The parameter ``displayname`` is optional and defaults to the value of
|
||||||
The parameter ``threepids`` is optional.
|
``user_id``.
|
||||||
The parameter ``avatar_url`` is optional.
|
|
||||||
The parameter ``admin`` is optional and defaults to 'false'.
|
The parameter ``threepids`` is optional and allows setting the third-party IDs
|
||||||
The parameter ``deactivated`` is optional and defaults to 'false'.
|
(email, msisdn) belonging to a user.
|
||||||
The parameter ``password`` is optional. If provided the user's password is updated and all devices are logged out.
|
|
||||||
|
The parameter ``avatar_url`` is optional. Must be a [MXC
|
||||||
|
URI](https://matrix.org/docs/spec/client_server/r0.6.0#matrix-content-mxc-uris).
|
||||||
|
|
||||||
|
The parameter ``admin`` is optional and defaults to ``false``.
|
||||||
|
|
||||||
|
The parameter ``deactivated`` is optional and defaults to ``false``.
|
||||||
|
|
||||||
|
The parameter ``password`` is optional. If provided, the user's password is
|
||||||
|
updated and all devices are logged out.
|
||||||
|
|
||||||
If the user already exists then optional parameters default to the current value.
|
If the user already exists then optional parameters default to the current value.
|
||||||
|
|
||||||
List Accounts
|
List Accounts
|
||||||
@ -51,16 +61,25 @@ 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.
|
including an ``access_token`` of a server admin.
|
||||||
The parameters ``from`` and ``limit`` are required only for pagination.
|
|
||||||
By default, a ``limit`` of 100 is used.
|
The parameter ``from`` is optional but used for pagination, denoting the
|
||||||
The parameter ``user_id`` can be used to select only users with user ids that
|
offset in the returned results. This should be treated as an opaque value and
|
||||||
contain this value.
|
not explicitly set to anything other than the return value of ``next_token``
|
||||||
The parameter ``guests=false`` can be used to exclude guest users,
|
from a previous call.
|
||||||
default is to include guest users.
|
|
||||||
The parameter ``deactivated=true`` can be used to include deactivated users,
|
The parameter ``limit`` is optional but is used for pagination, denoting the
|
||||||
default is to exclude deactivated users.
|
maximum number of items to return in this call. Defaults to ``100``.
|
||||||
If the endpoint does not return a ``next_token`` then there are no more users left.
|
|
||||||
It returns a JSON body like the following:
|
The parameter ``user_id`` is optional and filters to only users with user IDs
|
||||||
|
that contain this value.
|
||||||
|
|
||||||
|
The parameter ``guests`` is optional and if ``false`` will **exclude** guest users.
|
||||||
|
Defaults to ``true`` to include guest users.
|
||||||
|
|
||||||
|
The parameter ``deactivated`` is optional and if ``true`` will **include** deactivated users.
|
||||||
|
Defaults to ``false`` to exclude deactivated users.
|
||||||
|
|
||||||
|
A JSON body is returned with the following shape:
|
||||||
|
|
||||||
.. code:: json
|
.. code:: json
|
||||||
|
|
||||||
@ -73,7 +92,7 @@ It returns a JSON body like the following:
|
|||||||
"admin": 0,
|
"admin": 0,
|
||||||
"user_type": null,
|
"user_type": null,
|
||||||
"deactivated": 0,
|
"deactivated": 0,
|
||||||
"displayname": <User One>,
|
"displayname": "<User One>",
|
||||||
"avatar_url": null
|
"avatar_url": null
|
||||||
}, {
|
}, {
|
||||||
"name": "<user_id2>",
|
"name": "<user_id2>",
|
||||||
@ -82,7 +101,7 @@ It returns a JSON body like the following:
|
|||||||
"admin": 1,
|
"admin": 1,
|
||||||
"user_type": null,
|
"user_type": null,
|
||||||
"deactivated": 0,
|
"deactivated": 0,
|
||||||
"displayname": <User Two>,
|
"displayname": "<User Two>",
|
||||||
"avatar_url": "<avatar_url>"
|
"avatar_url": "<avatar_url>"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
@ -90,6 +109,11 @@ It returns a JSON body like the following:
|
|||||||
"total": 200
|
"total": 200
|
||||||
}
|
}
|
||||||
|
|
||||||
|
To paginate, check for ``next_token`` and if present, call the endpoint again
|
||||||
|
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 Account
|
||||||
=============
|
=============
|
||||||
|
Loading…
Reference in New Issue
Block a user