user_admin_api.rst 21 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762
  1. .. contents::
  2. Query User Account
  3. ==================
  4. This API returns information about a specific user account.
  5. The api is::
  6. GET /_synapse/admin/v2/users/<user_id>
  7. To use it, you will need to authenticate by providing an ``access_token`` for a
  8. server admin: see `README.rst <README.rst>`_.
  9. It returns a JSON body like the following:
  10. .. code:: json
  11. {
  12. "displayname": "User",
  13. "threepids": [
  14. {
  15. "medium": "email",
  16. "address": "<user_mail_1>"
  17. },
  18. {
  19. "medium": "email",
  20. "address": "<user_mail_2>"
  21. }
  22. ],
  23. "avatar_url": "<avatar_url>",
  24. "admin": false,
  25. "deactivated": false,
  26. "password_hash": "$2b$12$p9B4GkqYdRTPGD",
  27. "creation_ts": 1560432506,
  28. "appservice_id": null,
  29. "consent_server_notice_sent": null,
  30. "consent_version": null
  31. }
  32. URL parameters:
  33. - ``user_id``: fully-qualified user id: for example, ``@user:server.com``.
  34. Create or modify Account
  35. ========================
  36. This API allows an administrator to create or modify a user account with a
  37. specific ``user_id``.
  38. This api is::
  39. PUT /_synapse/admin/v2/users/<user_id>
  40. with a body of:
  41. .. code:: json
  42. {
  43. "password": "user_password",
  44. "displayname": "User",
  45. "threepids": [
  46. {
  47. "medium": "email",
  48. "address": "<user_mail_1>"
  49. },
  50. {
  51. "medium": "email",
  52. "address": "<user_mail_2>"
  53. }
  54. ],
  55. "avatar_url": "<avatar_url>",
  56. "admin": false,
  57. "deactivated": false
  58. }
  59. To use it, you will need to authenticate by providing an ``access_token`` for a
  60. server admin: see `README.rst <README.rst>`_.
  61. URL parameters:
  62. - ``user_id``: fully-qualified user id: for example, ``@user:server.com``.
  63. Body parameters:
  64. - ``password``, optional. If provided, the user's password is updated and all
  65. devices are logged out.
  66. - ``displayname``, optional, defaults to the value of ``user_id``.
  67. - ``threepids``, optional, allows setting the third-party IDs (email, msisdn)
  68. belonging to a user.
  69. - ``avatar_url``, optional, must be a
  70. `MXC URI <https://matrix.org/docs/spec/client_server/r0.6.0#matrix-content-mxc-uris>`_.
  71. - ``admin``, optional, defaults to ``false``.
  72. - ``deactivated``, optional. If unspecified, deactivation state will be left
  73. unchanged on existing accounts and set to ``false`` for new accounts.
  74. A user cannot be erased by deactivating with this API. For details on deactivating users see
  75. `Deactivate Account <#deactivate-account>`_.
  76. If the user already exists then optional parameters default to the current value.
  77. In order to re-activate an account ``deactivated`` must be set to ``false``. If
  78. users do not login via single-sign-on, a new ``password`` must be provided.
  79. List Accounts
  80. =============
  81. This API returns all local user accounts.
  82. The api is::
  83. GET /_synapse/admin/v2/users?from=0&limit=10&guests=false
  84. To use it, you will need to authenticate by providing an ``access_token`` for a
  85. server admin: see `README.rst <README.rst>`_.
  86. The parameter ``from`` is optional but used for pagination, denoting the
  87. offset in the returned results. This should be treated as an opaque value and
  88. not explicitly set to anything other than the return value of ``next_token``
  89. from a previous call.
  90. The parameter ``limit`` is optional but is used for pagination, denoting the
  91. maximum number of items to return in this call. Defaults to ``100``.
  92. The parameter ``user_id`` is optional and filters to only return users with user IDs
  93. that contain this value. This parameter is ignored when using the ``name`` parameter.
  94. The parameter ``name`` is optional and filters to only return users with user ID localparts
  95. **or** displaynames that contain this value.
  96. The parameter ``guests`` is optional and if ``false`` will **exclude** guest users.
  97. Defaults to ``true`` to include guest users.
  98. The parameter ``deactivated`` is optional and if ``true`` will **include** deactivated users.
  99. Defaults to ``false`` to exclude deactivated users.
  100. A JSON body is returned with the following shape:
  101. .. code:: json
  102. {
  103. "users": [
  104. {
  105. "name": "<user_id1>",
  106. "is_guest": 0,
  107. "admin": 0,
  108. "user_type": null,
  109. "deactivated": 0,
  110. "displayname": "<User One>",
  111. "avatar_url": null
  112. }, {
  113. "name": "<user_id2>",
  114. "is_guest": 0,
  115. "admin": 1,
  116. "user_type": null,
  117. "deactivated": 0,
  118. "displayname": "<User Two>",
  119. "avatar_url": "<avatar_url>"
  120. }
  121. ],
  122. "next_token": "100",
  123. "total": 200
  124. }
  125. To paginate, check for ``next_token`` and if present, call the endpoint again
  126. with ``from`` set to the value of ``next_token``. This will return a new page.
  127. If the endpoint does not return a ``next_token`` then there are no more users
  128. to paginate through.
  129. Query current sessions for a user
  130. =================================
  131. This API returns information about the active sessions for a specific user.
  132. The api is::
  133. GET /_synapse/admin/v1/whois/<user_id>
  134. and::
  135. GET /_matrix/client/r0/admin/whois/<userId>
  136. See also: `Client Server API Whois
  137. <https://matrix.org/docs/spec/client_server/r0.6.1#get-matrix-client-r0-admin-whois-userid>`_
  138. To use it, you will need to authenticate by providing an ``access_token`` for a
  139. server admin: see `README.rst <README.rst>`_.
  140. It returns a JSON body like the following:
  141. .. code:: json
  142. {
  143. "user_id": "<user_id>",
  144. "devices": {
  145. "": {
  146. "sessions": [
  147. {
  148. "connections": [
  149. {
  150. "ip": "1.2.3.4",
  151. "last_seen": 1417222374433,
  152. "user_agent": "Mozilla/5.0 ..."
  153. },
  154. {
  155. "ip": "1.2.3.10",
  156. "last_seen": 1417222374500,
  157. "user_agent": "Dalvik/2.1.0 ..."
  158. }
  159. ]
  160. }
  161. ]
  162. }
  163. }
  164. }
  165. ``last_seen`` is measured in milliseconds since the Unix epoch.
  166. Deactivate Account
  167. ==================
  168. This API deactivates an account. It removes active access tokens, resets the
  169. password, and deletes third-party IDs (to prevent the user requesting a
  170. password reset).
  171. It can also mark the user as GDPR-erased. This means messages sent by the
  172. user will still be visible by anyone that was in the room when these messages
  173. were sent, but hidden from users joining the room afterwards.
  174. The api is::
  175. POST /_synapse/admin/v1/deactivate/<user_id>
  176. with a body of:
  177. .. code:: json
  178. {
  179. "erase": true
  180. }
  181. To use it, you will need to authenticate by providing an ``access_token`` for a
  182. server admin: see `README.rst <README.rst>`_.
  183. The erase parameter is optional and defaults to ``false``.
  184. An empty body may be passed for backwards compatibility.
  185. The following actions are performed when deactivating an user:
  186. - Try to unpind 3PIDs from the identity server
  187. - Remove all 3PIDs from the homeserver
  188. - Delete all devices and E2EE keys
  189. - Delete all access tokens
  190. - Delete the password hash
  191. - Removal from all rooms the user is a member of
  192. - Remove the user from the user directory
  193. - Reject all pending invites
  194. - Remove all account validity information related to the user
  195. The following additional actions are performed during deactivation if``erase``
  196. is set to ``true``:
  197. - Remove the user's display name
  198. - Remove the user's avatar URL
  199. - Mark the user as erased
  200. Reset password
  201. ==============
  202. Changes the password of another user. This will automatically log the user out of all their devices.
  203. The api is::
  204. POST /_synapse/admin/v1/reset_password/<user_id>
  205. with a body of:
  206. .. code:: json
  207. {
  208. "new_password": "<secret>",
  209. "logout_devices": true
  210. }
  211. To use it, you will need to authenticate by providing an ``access_token`` for a
  212. server admin: see `README.rst <README.rst>`_.
  213. The parameter ``new_password`` is required.
  214. The parameter ``logout_devices`` is optional and defaults to ``true``.
  215. Get whether a user is a server administrator or not
  216. ===================================================
  217. The api is::
  218. GET /_synapse/admin/v1/users/<user_id>/admin
  219. To use it, you will need to authenticate by providing an ``access_token`` for a
  220. server admin: see `README.rst <README.rst>`_.
  221. A response body like the following is returned:
  222. .. code:: json
  223. {
  224. "admin": true
  225. }
  226. Change whether a user is a server administrator or not
  227. ======================================================
  228. Note that you cannot demote yourself.
  229. The api is::
  230. PUT /_synapse/admin/v1/users/<user_id>/admin
  231. with a body of:
  232. .. code:: json
  233. {
  234. "admin": true
  235. }
  236. To use it, you will need to authenticate by providing an ``access_token`` for a
  237. server admin: see `README.rst <README.rst>`_.
  238. List room memberships of an user
  239. ================================
  240. Gets a list of all ``room_id`` that a specific ``user_id`` is member.
  241. The API is::
  242. GET /_synapse/admin/v1/users/<user_id>/joined_rooms
  243. To use it, you will need to authenticate by providing an ``access_token`` for a
  244. server admin: see `README.rst <README.rst>`_.
  245. A response body like the following is returned:
  246. .. code:: json
  247. {
  248. "joined_rooms": [
  249. "!DuGcnbhHGaSZQoNQR:matrix.org",
  250. "!ZtSaPCawyWtxfWiIy:matrix.org"
  251. ],
  252. "total": 2
  253. }
  254. The server returns the list of rooms of which the user and the server
  255. are member. If the user is local, all the rooms of which the user is
  256. member are returned.
  257. **Parameters**
  258. The following parameters should be set in the URL:
  259. - ``user_id`` - fully qualified: for example, ``@user:server.com``.
  260. **Response**
  261. The following fields are returned in the JSON response body:
  262. - ``joined_rooms`` - An array of ``room_id``.
  263. - ``total`` - Number of rooms.
  264. List media of an user
  265. ================================
  266. Gets a list of all local media that a specific ``user_id`` has created.
  267. The response is ordered by creation date descending and media ID descending.
  268. The newest media is on top.
  269. The API is::
  270. GET /_synapse/admin/v1/users/<user_id>/media
  271. To use it, you will need to authenticate by providing an ``access_token`` for a
  272. server admin: see `README.rst <README.rst>`_.
  273. A response body like the following is returned:
  274. .. code:: json
  275. {
  276. "media": [
  277. {
  278. "created_ts": 100400,
  279. "last_access_ts": null,
  280. "media_id": "qXhyRzulkwLsNHTbpHreuEgo",
  281. "media_length": 67,
  282. "media_type": "image/png",
  283. "quarantined_by": null,
  284. "safe_from_quarantine": false,
  285. "upload_name": "test1.png"
  286. },
  287. {
  288. "created_ts": 200400,
  289. "last_access_ts": null,
  290. "media_id": "FHfiSnzoINDatrXHQIXBtahw",
  291. "media_length": 67,
  292. "media_type": "image/png",
  293. "quarantined_by": null,
  294. "safe_from_quarantine": false,
  295. "upload_name": "test2.png"
  296. }
  297. ],
  298. "next_token": 3,
  299. "total": 2
  300. }
  301. To paginate, check for ``next_token`` and if present, call the endpoint again
  302. with ``from`` set to the value of ``next_token``. This will return a new page.
  303. If the endpoint does not return a ``next_token`` then there are no more
  304. reports to paginate through.
  305. **Parameters**
  306. The following parameters should be set in the URL:
  307. - ``user_id`` - string - fully qualified: for example, ``@user:server.com``.
  308. - ``limit``: string representing a positive integer - Is optional but is used for pagination,
  309. denoting the maximum number of items to return in this call. Defaults to ``100``.
  310. - ``from``: string representing a positive integer - Is optional but used for pagination,
  311. denoting the offset in the returned results. This should be treated as an opaque value and
  312. not explicitly set to anything other than the return value of ``next_token`` from a previous call.
  313. Defaults to ``0``.
  314. **Response**
  315. The following fields are returned in the JSON response body:
  316. - ``media`` - An array of objects, each containing information about a media.
  317. Media objects contain the following fields:
  318. - ``created_ts`` - integer - Timestamp when the content was uploaded in ms.
  319. - ``last_access_ts`` - integer - Timestamp when the content was last accessed in ms.
  320. - ``media_id`` - string - The id used to refer to the media.
  321. - ``media_length`` - integer - Length of the media in bytes.
  322. - ``media_type`` - string - The MIME-type of the media.
  323. - ``quarantined_by`` - string - The user ID that initiated the quarantine request
  324. for this media.
  325. - ``safe_from_quarantine`` - bool - Status if this media is safe from quarantining.
  326. - ``upload_name`` - string - The name the media was uploaded with.
  327. - ``next_token``: integer - Indication for pagination. See above.
  328. - ``total`` - integer - Total number of media.
  329. Login as a user
  330. ===============
  331. Get an access token that can be used to authenticate as that user. Useful for
  332. when admins wish to do actions on behalf of a user.
  333. The API is::
  334. POST /_synapse/admin/v1/users/<user_id>/login
  335. {}
  336. An optional ``valid_until_ms`` field can be specified in the request body as an
  337. integer timestamp that specifies when the token should expire. By default tokens
  338. do not expire.
  339. A response body like the following is returned:
  340. .. code:: json
  341. {
  342. "access_token": "<opaque_access_token_string>"
  343. }
  344. This API does *not* generate a new device for the user, and so will not appear
  345. their ``/devices`` list, and in general the target user should not be able to
  346. tell they have been logged in as.
  347. To expire the token call the standard ``/logout`` API with the token.
  348. Note: The token will expire if the *admin* user calls ``/logout/all`` from any
  349. of their devices, but the token will *not* expire if the target user does the
  350. same.
  351. User devices
  352. ============
  353. List all devices
  354. ----------------
  355. Gets information about all devices for a specific ``user_id``.
  356. The API is::
  357. GET /_synapse/admin/v2/users/<user_id>/devices
  358. To use it, you will need to authenticate by providing an ``access_token`` for a
  359. server admin: see `README.rst <README.rst>`_.
  360. A response body like the following is returned:
  361. .. code:: json
  362. {
  363. "devices": [
  364. {
  365. "device_id": "QBUAZIFURK",
  366. "display_name": "android",
  367. "last_seen_ip": "1.2.3.4",
  368. "last_seen_ts": 1474491775024,
  369. "user_id": "<user_id>"
  370. },
  371. {
  372. "device_id": "AUIECTSRND",
  373. "display_name": "ios",
  374. "last_seen_ip": "1.2.3.5",
  375. "last_seen_ts": 1474491775025,
  376. "user_id": "<user_id>"
  377. }
  378. ],
  379. "total": 2
  380. }
  381. **Parameters**
  382. The following parameters should be set in the URL:
  383. - ``user_id`` - fully qualified: for example, ``@user:server.com``.
  384. **Response**
  385. The following fields are returned in the JSON response body:
  386. - ``devices`` - An array of objects, each containing information about a device.
  387. Device objects contain the following fields:
  388. - ``device_id`` - Identifier of device.
  389. - ``display_name`` - Display name set by the user for this device.
  390. Absent if no name has been set.
  391. - ``last_seen_ip`` - The IP address where this device was last seen.
  392. (May be a few minutes out of date, for efficiency reasons).
  393. - ``last_seen_ts`` - The timestamp (in milliseconds since the unix epoch) when this
  394. devices was last seen. (May be a few minutes out of date, for efficiency reasons).
  395. - ``user_id`` - Owner of device.
  396. - ``total`` - Total number of user's devices.
  397. Delete multiple devices
  398. ------------------
  399. Deletes the given devices for a specific ``user_id``, and invalidates
  400. any access token associated with them.
  401. The API is::
  402. POST /_synapse/admin/v2/users/<user_id>/delete_devices
  403. {
  404. "devices": [
  405. "QBUAZIFURK",
  406. "AUIECTSRND"
  407. ],
  408. }
  409. To use it, you will need to authenticate by providing an ``access_token`` for a
  410. server admin: see `README.rst <README.rst>`_.
  411. An empty JSON dict is returned.
  412. **Parameters**
  413. The following parameters should be set in the URL:
  414. - ``user_id`` - fully qualified: for example, ``@user:server.com``.
  415. The following fields are required in the JSON request body:
  416. - ``devices`` - The list of device IDs to delete.
  417. Show a device
  418. ---------------
  419. Gets information on a single device, by ``device_id`` for a specific ``user_id``.
  420. The API is::
  421. GET /_synapse/admin/v2/users/<user_id>/devices/<device_id>
  422. To use it, you will need to authenticate by providing an ``access_token`` for a
  423. server admin: see `README.rst <README.rst>`_.
  424. A response body like the following is returned:
  425. .. code:: json
  426. {
  427. "device_id": "<device_id>",
  428. "display_name": "android",
  429. "last_seen_ip": "1.2.3.4",
  430. "last_seen_ts": 1474491775024,
  431. "user_id": "<user_id>"
  432. }
  433. **Parameters**
  434. The following parameters should be set in the URL:
  435. - ``user_id`` - fully qualified: for example, ``@user:server.com``.
  436. - ``device_id`` - The device to retrieve.
  437. **Response**
  438. The following fields are returned in the JSON response body:
  439. - ``device_id`` - Identifier of device.
  440. - ``display_name`` - Display name set by the user for this device.
  441. Absent if no name has been set.
  442. - ``last_seen_ip`` - The IP address where this device was last seen.
  443. (May be a few minutes out of date, for efficiency reasons).
  444. - ``last_seen_ts`` - The timestamp (in milliseconds since the unix epoch) when this
  445. devices was last seen. (May be a few minutes out of date, for efficiency reasons).
  446. - ``user_id`` - Owner of device.
  447. Update a device
  448. ---------------
  449. Updates the metadata on the given ``device_id`` for a specific ``user_id``.
  450. The API is::
  451. PUT /_synapse/admin/v2/users/<user_id>/devices/<device_id>
  452. {
  453. "display_name": "My other phone"
  454. }
  455. To use it, you will need to authenticate by providing an ``access_token`` for a
  456. server admin: see `README.rst <README.rst>`_.
  457. An empty JSON dict is returned.
  458. **Parameters**
  459. The following parameters should be set in the URL:
  460. - ``user_id`` - fully qualified: for example, ``@user:server.com``.
  461. - ``device_id`` - The device to update.
  462. The following fields are required in the JSON request body:
  463. - ``display_name`` - The new display name for this device. If not given,
  464. the display name is unchanged.
  465. Delete a device
  466. ---------------
  467. Deletes the given ``device_id`` for a specific ``user_id``,
  468. and invalidates any access token associated with it.
  469. The API is::
  470. DELETE /_synapse/admin/v2/users/<user_id>/devices/<device_id>
  471. {}
  472. To use it, you will need to authenticate by providing an ``access_token`` for a
  473. server admin: see `README.rst <README.rst>`_.
  474. An empty JSON dict is returned.
  475. **Parameters**
  476. The following parameters should be set in the URL:
  477. - ``user_id`` - fully qualified: for example, ``@user:server.com``.
  478. - ``device_id`` - The device to delete.
  479. List all pushers
  480. ================
  481. Gets information about all pushers for a specific ``user_id``.
  482. The API is::
  483. GET /_synapse/admin/v1/users/<user_id>/pushers
  484. To use it, you will need to authenticate by providing an ``access_token`` for a
  485. server admin: see `README.rst <README.rst>`_.
  486. A response body like the following is returned:
  487. .. code:: json
  488. {
  489. "pushers": [
  490. {
  491. "app_display_name":"HTTP Push Notifications",
  492. "app_id":"m.http",
  493. "data": {
  494. "url":"example.com"
  495. },
  496. "device_display_name":"pushy push",
  497. "kind":"http",
  498. "lang":"None",
  499. "profile_tag":"",
  500. "pushkey":"a@example.com"
  501. }
  502. ],
  503. "total": 1
  504. }
  505. **Parameters**
  506. The following parameters should be set in the URL:
  507. - ``user_id`` - fully qualified: for example, ``@user:server.com``.
  508. **Response**
  509. The following fields are returned in the JSON response body:
  510. - ``pushers`` - An array containing the current pushers for the user
  511. - ``app_display_name`` - string - A string that will allow the user to identify
  512. what application owns this pusher.
  513. - ``app_id`` - string - This is a reverse-DNS style identifier for the application.
  514. Max length, 64 chars.
  515. - ``data`` - A dictionary of information for the pusher implementation itself.
  516. - ``url`` - string - Required if ``kind`` is ``http``. The URL to use to send
  517. notifications to.
  518. - ``format`` - string - The format to use when sending notifications to the
  519. Push Gateway.
  520. - ``device_display_name`` - string - A string that will allow the user to identify
  521. what device owns this pusher.
  522. - ``profile_tag`` - string - This string determines which set of device specific rules
  523. this pusher executes.
  524. - ``kind`` - string - The kind of pusher. "http" is a pusher that sends HTTP pokes.
  525. - ``lang`` - string - The preferred language for receiving notifications
  526. (e.g. 'en' or 'en-US')
  527. - ``profile_tag`` - string - This string determines which set of device specific rules
  528. this pusher executes.
  529. - ``pushkey`` - string - This is a unique identifier for this pusher.
  530. Max length, 512 bytes.
  531. - ``total`` - integer - Number of pushers.
  532. See also `Client-Server API Spec <https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-pushers>`_