From 012cd78bb2d46a7719021988e4106d377d9464bf Mon Sep 17 00:00:00 2001 From: anoadragon453 Date: Fri, 5 May 2023 14:52:44 +0000 Subject: deploy: 7c95b65873c7a858388b9c99c7e9e15dc5ccb2b5 --- develop/admin_api/user_admin_api.html | 107 +++++++++++++++++++++------------- 1 file changed, 68 insertions(+), 39 deletions(-) (limited to 'develop/admin_api') diff --git a/develop/admin_api/user_admin_api.html b/develop/admin_api/user_admin_api.html index 5501e0dabe..55af2cadb6 100644 --- a/develop/admin_api/user_admin_api.html +++ b/develop/admin_api/user_admin_api.html @@ -200,7 +200,7 @@ for a server admin: see Admin API
  • 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 specific user_id.

    This api is:

    @@ -209,28 +209,29 @@ specific user_id.

    with a body of:

    {
     "password": "user_password",
-    "displayname": "User",
+    "logout_devices": false,
+    "displayname": "Alice Marigold",
+    "avatar_url": "mxc://example.com/abcde12345",
     "threepids": [
         {
             "medium": "email",
-            "address": "<user_mail_1>"
+            "address": "alice@example.com"
         },
         {
             "medium": "email",
-            "address": "<user_mail_2>"
+            "address": "alice@domain.org"
         }
     ],
     "external_ids": [
         {
-            "auth_provider": "<provider1>",
-            "external_id": "<user_id_provider_1>"
+            "auth_provider": "example",
+            "external_id": "12345"
         },
         {
-            "auth_provider": "<provider2>",
-            "external_id": "<user_id_provider_2>"
+            "auth_provider": "example2",
+            "external_id": "abc54321"
         }
     ],
-    "avatar_url": "<avatar_url>",
     "admin": false,
     "deactivated": false,
     "user_type": null
@@ -243,46 +244,74 @@ specific user_id.
    
 
 
    URL parameters:
    
 
      
-
    • user_id: fully-qualified user id: for example, @user:server.com.
      • 
+
    • user_id - A fully-qualified user id. For example, @user:server.com.
      • 
 
    
 
    Body parameters:
    
 
      
-
    • password - string, optional. If provided, the user's password is updated and all
-devices are logged out, unless logout_devices is set to false.
      • 
-
    • logout_devices - bool, optional, defaults to true. If set to false, devices aren't
-logged out even when password is provided.
      • 
-
    • displayname - string, optional, defaults to the value of user_id.
      • 
-
    • threepids - array, optional, allows setting the third-party IDs (email, msisdn)
+
    • 
+
      password - string, optional. If provided, the user's password is updated and all
+devices are logged out, unless logout_devices is set to false.
      
+
      • 
+
    • 
+
      logout_devices - bool, optional, defaults to true. If set to false, devices aren't
+logged out even when password is provided.
      
+
      • 
+
    • 
+
      displayname - string, optional. If set to an empty string (""), the user's display name
+will be removed.
      
+
      • 
+
    • 
+
      avatar_url - string, optional. Must be a
+MXC URI.
+If set to an empty string (""), the user's avatar is removed.
      
+
      • 
+
    • 
+
      threepids - array, optional. If provided, the user's third-party IDs (email, msisdn) are
+entirely replaced with the given list. Each item in the array is an object with the following
+fields:
      
 
        
-
      • medium - string. Kind of third-party ID, either email or msisdn.
        • 
-
      • address - string. Value of third-party ID.
-belonging to a user.
        • 
+
      • medium - string, required. The type of third-party ID, either email or msisdn (phone number).
        • 
+
      • address - string, required. The third-party ID itself, e.g. alice@example.com for email or
+447470274584 (for a phone number with country code "44") and 19254857364 (for a phone number
+with country code "1") for msisdn.
+Note: If a threepid is removed from a user via this option, Synapse will also attempt to remove
+that threepid from any identity servers it is aware has a binding for it.
        • 
 
      
 
      • 
-
    • external_ids - array, optional. Allow setting the identifier of the external identity
-provider for SSO (Single sign-on). Details in the configuration manual under the
-sections sso and oidc_providers.
+
    • 
+
      external_ids - array, optional. Allow setting the identifier of the external identity
+provider for SSO (Single sign-on). More details are in the configuration manual under the
+sections sso and oidc_providers.
      
 
        
-
      • auth_provider - string. ID of the external identity provider. Value of idp_id
-in the homeserver configuration. Note that no error is raised if the provided
-value is not in the homeserver configuration.
        • 
-
      • external_id - string, user ID in the external identity provider.
        • 
+
      • auth_provider - string, required. The unique, internal ID of the external identity provider.
+The same as idp_id from the homeserver configuration. Note that no error is raised if the
+provided value is not in the homeserver configuration.
        • 
+
      • external_id - string, required. An identifier for the user in the external identity provider.
+When the user logs in to the identity provider, this must be the unique ID that they map to.
        • 
 
      
 
      • 
-
    • avatar_url - string, optional, must be a
-MXC URI.
      • 
-
    • admin - bool, optional, defaults to false.
      • 
-
    • deactivated - bool, optional. If unspecified, deactivation state will be left
-unchanged on existing accounts and set to false for new accounts.
-A user cannot be erased by deactivating with this API. For details on
-deactivating users see Deactivate Account.
      • 
-
    • user_type - string or null, optional. If provided, the user type will be
-adjusted. If null given, the user type will be cleared. Other 
-allowed options are: bot and support.
      • 
+
    • 
+
      admin - bool, optional, defaults to false. Whether the user is a homeserver administrator,
+granting them access to the Admin API, among other things.
      
+
      • 
+
    • 
+
      deactivated - bool, optional. If unspecified, deactivation state will be left unchanged.
      
+
      Note: the password field must also be set if both of the following are true:
      
+
        
+
      • deactivated is set to false and the user was previously deactivated (you are reactivating this user)
        • 
+
      • Users are allowed to set their password on this homeserver (both password_config.enabled and
+password_config.localdb_enabled config options are set to true).
+Users' passwords are wiped upon account deactivation, hence the need to set a new one here.
        • 
+
      
+
      Note: a user cannot be erased with this API. For more details on
+deactivating and erasing users see Deactivate Account.
      
+
      • 
+
    • 
+
      user_type - string or null, optional. If not provided, the user type will be
+not be changed. If null is given, the user type will be cleared.
+Other allowed options are: bot and support.
      
+
      • 
 
    
-
    If the user already exists then optional parameters default to the current value.
    
-
    In order to re-activate an account deactivated must be set to false. If
-users do not login via single-sign-on, a new password must be provided.
    
 
    List Accounts
    
 
    This API returns all local user accounts.
 By default, the response is ordered by ascending user ID.
    
-- 
cgit 1.5.1