user_admin_api.rst 4.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201
  1. Create or modify Account
  2. ========================
  3. This API allows an administrator to create or modify a user account with a
  4. specific ``user_id``.
  5. This api is::
  6. PUT /_synapse/admin/v2/users/<user_id>
  7. with a body of:
  8. .. code:: json
  9. {
  10. "password": "user_password",
  11. "displayname": "User",
  12. "avatar_url": "<avatar_url>",
  13. "admin": false,
  14. "deactivated": false
  15. }
  16. including an ``access_token`` of a server admin.
  17. The parameter ``displayname`` is optional and defaults to ``user_id``.
  18. The parameter ``avatar_url`` is optional.
  19. The parameter ``admin`` is optional and defaults to 'false'.
  20. The parameter ``deactivated`` is optional and defaults to 'false'.
  21. If the user already exists then optional parameters default to the current value.
  22. List Accounts
  23. =============
  24. This API returns all local user accounts.
  25. The api is::
  26. GET /_synapse/admin/v2/users?from=0&limit=10&guests=false
  27. including an ``access_token`` of a server admin.
  28. The parameters ``from`` and ``limit`` are required only for pagination.
  29. By default, a ``limit`` of 100 is used.
  30. The parameter ``user_id`` can be used to select only users with user ids that
  31. contain this value.
  32. The parameter ``guests=false`` can be used to exclude guest users,
  33. default is to include guest users.
  34. The parameter ``deactivated=true`` can be used to include deactivated users,
  35. default is to exclude deactivated users.
  36. If the endpoint does not return a ``next_token`` then there are no more users left.
  37. It returns a JSON body like the following:
  38. .. code:: json
  39. {
  40. "users": [
  41. {
  42. "name": "<user_id1>",
  43. "password_hash": "<password_hash1>",
  44. "is_guest": 0,
  45. "admin": 0,
  46. "user_type": null,
  47. "deactivated": 0
  48. }, {
  49. "name": "<user_id2>",
  50. "password_hash": "<password_hash2>",
  51. "is_guest": 0,
  52. "admin": 1,
  53. "user_type": null,
  54. "deactivated": 0
  55. }
  56. ],
  57. "next_token": "100"
  58. }
  59. Query Account
  60. =============
  61. This API returns information about a specific user account.
  62. The api is::
  63. GET /_synapse/admin/v1/whois/<user_id> (deprecated)
  64. GET /_synapse/admin/v2/users/<user_id>
  65. including an ``access_token`` of a server admin.
  66. It returns a JSON body like the following:
  67. .. code:: json
  68. {
  69. "user_id": "<user_id>",
  70. "devices": {
  71. "": {
  72. "sessions": [
  73. {
  74. "connections": [
  75. {
  76. "ip": "1.2.3.4",
  77. "last_seen": 1417222374433,
  78. "user_agent": "Mozilla/5.0 ..."
  79. },
  80. {
  81. "ip": "1.2.3.10",
  82. "last_seen": 1417222374500,
  83. "user_agent": "Dalvik/2.1.0 ..."
  84. }
  85. ]
  86. }
  87. ]
  88. }
  89. }
  90. }
  91. ``last_seen`` is measured in milliseconds since the Unix epoch.
  92. Deactivate Account
  93. ==================
  94. This API deactivates an account. It removes active access tokens, resets the
  95. password, and deletes third-party IDs (to prevent the user requesting a
  96. password reset). It can also mark the user as GDPR-erased (stopping their data
  97. from distributed further, and deleting it entirely if there are no other
  98. references to it).
  99. The api is::
  100. POST /_synapse/admin/v1/deactivate/<user_id>
  101. with a body of:
  102. .. code:: json
  103. {
  104. "erase": true
  105. }
  106. including an ``access_token`` of a server admin.
  107. The erase parameter is optional and defaults to 'false'.
  108. An empty body may be passed for backwards compatibility.
  109. Reset password
  110. ==============
  111. Changes the password of another user. This will automatically log the user out of all their devices.
  112. The api is::
  113. POST /_synapse/admin/v1/reset_password/<user_id>
  114. with a body of:
  115. .. code:: json
  116. {
  117. "new_password": "<secret>"
  118. }
  119. including an ``access_token`` of a server admin.
  120. Get whether a user is a server administrator or not
  121. ===================================================
  122. The api is::
  123. GET /_synapse/admin/v1/users/<user_id>/admin
  124. including an ``access_token`` of a server admin.
  125. A response body like the following is returned:
  126. .. code:: json
  127. {
  128. "admin": true
  129. }
  130. Change whether a user is a server administrator or not
  131. ======================================================
  132. Note that you cannot demote yourself.
  133. The api is::
  134. PUT /_synapse/admin/v1/users/<user_id>/admin
  135. with a body of:
  136. .. code:: json
  137. {
  138. "admin": true
  139. }
  140. including an ``access_token`` of a server admin.