Create a reusable User Management template for Windows endpoints.

Open in ChatGPT Open in ChatGPT to ask questions about this page
Open in Claude Open in Claude to ask questions about this page
Copy as MarkdownCopy this page as markdown to use with AI assistants
View as Markdown Open this page as markdown in a new tab

Creates a User Management template to manage local user accounts on Windows target endpoints. The configuration is saved as a reusable template that can be deployed later. Each entry in configDetails carries one action - addUser, modifyUser, removeUser or changePassword - and several entries may be sent to act on several accounts in one template. Disabling, enabling, locking and unlocking an account are all modifyUser actions driven by the isAccountDisabled and isAccountLock flags. Use the returned templateId with the Deploy Configuration Template API to deploy it to targets.

Request URL

https://{serverurl}/dcapi/config-policies/v2/windows/userMgmt Copied!

Scope

DesktopCentralCloud.Configurations.CREATECopied!

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Request Parameters

- Request Headers

Content-TypestringMandatory
application/jsonapplication/jsonCopied!

Media type of the request body, as consumed by the endpoint.

AcceptstringMandatory
application/jsonapplication/jsonCopied!

Media type of the response body, as produced by the endpoint.

- Request Body

application/json
JSON Object
Hide Sub-Attributes
labelstringMandatory

Name of the configuration. Returned as templateName in the response.

descriptionstringOptional

Free-text description of the configuration. May be an empty string.

configTypestringMandatory

What the configuration is applied to. Must be computer - User Management applies to computers only.

applyAlwaysbooleanOptional

Reapply the configuration at every agent refresh, even when it has already been applied successfully.

applyAtStartupLogonbooleanOptional

Apply the configuration at endpoint startup.

applyAtRefreshbooleanOptional

Apply the configuration at the scheduled agent refresh.

enableRetrybooleanOptional

Retry the configuration on the endpoint when it fails. noOfRetries sets how many attempts are made.

enableRefreshMinRetrybooleanOptional

Honour refreshMinRetry as the minimum gap between two retries at refresh.

enableLogonStartupMinRetrybooleanOptional

Honour logonStartupMinRetry as the minimum gap between two retries at startup or logon.

noOfRetriesintegerOptional

Number of retry attempts made after a failure. Read only when enableRetry is true.

refreshMinRetryintegerOptional

Minimum number of minutes between two retries at refresh. Read only when enableRefreshMinRetry is true.

logonStartupMinRetryintegerOptional

Minimum number of minutes between two retries at startup or logon. Read only when enableLogonStartupMinRetry is true.

configDetailsJSON ArrayMandatory

One entry per user account action - addUser, modifyUser, removeUser or changePassword - applied in the order they appear.

Show Sub-Attributes
JSON Object
Show Sub-Attributes
actionstringMandatory

What to do with the account named in userName. Allowed values:
addUser = creates a local account
modifyUser = changes an existing one
removeUser = deletes it
changePassword = resets its password

Disabling, enabling, locking and unlocking are all modifyUser actions driven by isAccountDisabled and isAccountLock - there is no separate disableUser or enableUser action. Mandatory, and matched case-insensitively.

userNamestringMandatory

Name of the local account the action applies to. Mandatory, and capped at 20 characters.

fullNamestringOptional

Full display name of the account. Read only for addUser and modifyUser.

userDescriptionstringOptional

Description shown against the account on the endpoint. Read only for addUser and modifyUser.

passwordstringOptional

Password to set on the account: the initial password for addUser, or the new password for changePassword, where it is mandatory unless retainOldPassword is true. Sent encrypted and never returned. Windows does not ask for the existing password, so there is no oldPassword field.

passwordHintstringOptional

Hint shown at the logon screen when the password is entered incorrectly. Read only for addUser and changePassword, and ignored when left empty.

retainOldPasswordbooleanOptional

Keep the password already saved against this configuration instead of applying the value in password. Read for addUser, modifyUser and changePassword, and honoured only while editing an existing template - on a new template there is no saved password to keep. Default: false

overwriteUserbooleanOptional

Overwrite the account when addUser is used and an account of that name already exists. Read only for addUser. Default: false

deleteUserProfilebooleanOptional

Also delete the account profile directory from the endpoint. Read only for removeUser. Default: false

userMustChangePasswordintegerOptional

Force the user to change the password at the next logon. Allowed values:
1 = enabled
2 = disabled
3 = not configured

Read only for addUser and modifyUser. It cannot be 1 at the same time as userCantChangePassword or pwdNeverExpires. Default: 3

userCantChangePasswordintegerOptional

Prevent the user from changing their own password. Allowed values:
1 = enabled
2 = disabled
3 = not configured

Read only for addUser and modifyUser. It cannot be 1 at the same time as userMustChangePassword. Default: 3

pwdNeverExpiresintegerOptional

Exempt the account password from the expiry policy. Allowed values:
1 = enabled
2 = disabled
3 = not configured

Read only for addUser and modifyUser. It cannot be 1 at the same time as userMustChangePassword. Default: 3

isAccountDisabledintegerOptional

Disable the account. Allowed values:
1 = enabled (the account is disabled)
2 = disabled (the account is usable)
3 = not configured

Read only for addUser and modifyUser - use modifyUser with this flag to disable or re-enable an account. Default: 3

isAccountLockintegerOptional

Lock the account out. Allowed values:
1 = enabled (the account is locked)
2 = disabled (the account is unlocked)
3 = not configured

Read only for addUser and modifyUser. Default: 3

homeFolderintegerOptional

Where the home folder lives. Allowed values:
1 = a local path given by localPath
2 = a mapped drive given by connectMap and connectMapTo

Read only for addUser and modifyUser. Default: 1

addMemberstringOptional

Comma-separated local groups the account is added to (e.g., "users,administrators"). Read only for addUser and modifyUser. Default: "users"

removeMemberstringOptional

Comma-separated local groups the account is removed from. Read only for modifyUser.

logonScriptstringOptional

Path of a script run when the account logs on. Read only for addUser and modifyUser.

profilePathstringOptional

Path of the roaming profile directory for the account. Read only for addUser and modifyUser.

localPathstringOptional

Local home folder path for the account. Read only for addUser and modifyUser, and only when homeFolder is 1.

connectMapstringOptional

Drive letter, from D: to Z:, the home folder is mapped to. Read only for addUser and modifyUser, and only when homeFolder is 2.

connectMapTostringOptional

UNC path the home folder drive letter is mapped to (e.g., "\server\share"). Read only for addUser and modifyUser, and only when homeFolder is 2.

enableEmailNotifybooleanOptional

Send an email to the addresses listed in email once the deployment finishes.

enableNotificationbooleanOptional

Notify the endpoint user about this deployment. notificationDuration and notificationEnabledDays are read only when this is true.

emailstringOptional

Comma-separated email addresses notified about the deployment. May be an empty string when enableEmailNotify is false.

notificationDurationintegerOptional

How long a deployment notification stays on screen for the endpoint user. Read only when enableNotification is true.

notificationEnabledDaysintegerOptional

Number of days for which deployment notifications stay enabled. Read only when enableNotification is true.

Examples

Add User▼
Add User -- Create a new local user account with action addUser.
Remove User -- Delete a local user account with action removeUser.
Disable User -- Disable a local user account with action modifyUser and isAccountDisabled 1.
Enable User -- Re-enable a disabled local user account with action modifyUser and isAccountDisabled 2.
Reset Password -- Reset the password of an existing local user account with action changePassword.

Sample Request

Curl
Java
Python
Deluge
PowerShell
Copied!
curl --request POST \
  --url https://appdomains/dcapi/config-policies/v2/windows/userMgmt \
  --header 'Accept: application/json' \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52' \
  --header 'Content-Type: application/json' \
  --data '{"configDetails":[{"action":"addUser","userName":"testuser"}],"label":"Sample USER_MGMT Config","configType":"computer"}'

Sample Request Body - Add User

Create a local account and add it to the Users group. The account flags take 1 = enabled, 2 = disabled, 3 = not configured; userMustChangePassword cannot be 1 at the same time as userCantChangePassword or pwdNeverExpires. homeFolder 1 selects a local home folder given by localPath.

Copied!
  {
    "applyAtRefresh": false,
    "applyAlways": false,
    "description": "Created through the Config Policies API.",
    "label": "Sample USER_MGMT Config",
    "configType": "computer",
    "applyAtStartupLogon": true,
    "noOfRetries": 2,
    "refreshMinRetry": 1,
    "notificationEnabledDays": 3,
    "enableLogonStartupMinRetry": false,
    "logonStartupMinRetry": 1,
    "configDetails": [
      {
        "addMember": "users",
        "userDescription": "Local test account",
        "userCantChangePassword": 2,
        "isAccountDisabled": 2,
        "fullName": "Test User",
        "pwdNeverExpires": 2,
        "userName": "testuser",
        "userMustChangePassword": 1,
        "password": "P@ssw0rd",
        "homeFolder": 1,
        "overwriteUser": false,
        "localPath": "C:\\Users\\testuser",
        "action": "addUser",
        "isAccountLock": 3
      }
    ],
    "enableNotification": false,
    "enableEmailNotify": false,
    "notificationDuration": 6,
    "enableRetry": false,
    "enableRefreshMinRetry": false,
    "email": ""
  }
                
▼ Show full

Sample Request

Curl
Java
Python
Deluge
PowerShell
Copied!
curl --request POST \
  --url https://appdomains/dcapi/config-policies/v2/windows/userMgmt \
  --header 'Accept: application/json' \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52' \
  --header 'Content-Type: application/json' \
  --data '{"configDetails":[{"action":"removeUser","userName":"olduser"}],"label":"Delete Test User","configType":"computer"}'

Sample Request Body - Remove User

Delete a local user account. The action is removeUser, and deleteUserProfile also removes the account profile directory from the endpoint.

Copied!
  {
    "applyAtRefresh": false,
    "applyAlways": false,
    "description": "Created through the Config Policies API.",
    "label": "Delete Test User",
    "configType": "computer",
    "applyAtStartupLogon": true,
    "noOfRetries": 2,
    "refreshMinRetry": 1,
    "notificationEnabledDays": 3,
    "enableLogonStartupMinRetry": false,
    "logonStartupMinRetry": 1,
    "configDetails": [
      {
        "deleteUserProfile": true,
        "action": "removeUser",
        "userName": "olduser"
      }
    ],
    "enableNotification": false,
    "enableEmailNotify": false,
    "notificationDuration": 6,
    "enableRetry": false,
    "enableRefreshMinRetry": false,
    "email": ""
  }
                
▼ Show full

Sample Request

Curl
Java
Python
Deluge
PowerShell
Copied!
curl --request POST \
  --url https://appdomains/dcapi/config-policies/v2/windows/userMgmt \
  --header 'Accept: application/json' \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52' \
  --header 'Content-Type: application/json' \
  --data '{"configDetails":[{"action":"modifyUser","userName":"Guest"}],"label":"Disable Guest Account","configType":"computer"}'

Sample Request Body - Disable User

Disable a local user account. There is no disableUser action - use modifyUser and set isAccountDisabled to 1 (enabled).

Copied!
  {
    "applyAtRefresh": false,
    "applyAlways": false,
    "description": "Created through the Config Policies API.",
    "label": "Disable Guest Account",
    "configType": "computer",
    "applyAtStartupLogon": true,
    "noOfRetries": 2,
    "refreshMinRetry": 1,
    "notificationEnabledDays": 3,
    "enableLogonStartupMinRetry": false,
    "logonStartupMinRetry": 1,
    "configDetails": [
      {
        "userMustChangePassword": 3,
        "userCantChangePassword": 3,
        "isAccountDisabled": 1,
        "action": "modifyUser",
        "pwdNeverExpires": 3,
        "userName": "Guest",
        "isAccountLock": 3
      }
    ],
    "enableNotification": false,
    "enableEmailNotify": false,
    "notificationDuration": 6,
    "enableRetry": false,
    "enableRefreshMinRetry": false,
    "email": ""
  }
                
▼ Show full

Sample Request

Curl
Java
Python
Deluge
PowerShell
Copied!
curl --request POST \
  --url https://appdomains/dcapi/config-policies/v2/windows/userMgmt \
  --header 'Accept: application/json' \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52' \
  --header 'Content-Type: application/json' \
  --data '{"configDetails":[{"action":"modifyUser","userName":"helpdesk"}],"label":"Enable Admin Account","configType":"computer"}'

Sample Request Body - Enable User

Re-enable a disabled local user account and remove it from the Administrators group. There is no enableUser action - use modifyUser and set isAccountDisabled to 2 (disabled).

Copied!
  {
    "applyAtRefresh": false,
    "applyAlways": false,
    "description": "Created through the Config Policies API.",
    "label": "Enable Admin Account",
    "configType": "computer",
    "applyAtStartupLogon": true,
    "noOfRetries": 2,
    "refreshMinRetry": 1,
    "notificationEnabledDays": 3,
    "enableLogonStartupMinRetry": false,
    "logonStartupMinRetry": 1,
    "configDetails": [
      {
        "userMustChangePassword": 3,
        "removeMember": "administrators",
        "userCantChangePassword": 3,
        "isAccountDisabled": 2,
        "action": "modifyUser",
        "pwdNeverExpires": 3,
        "userName": "helpdesk",
        "isAccountLock": 2
      }
    ],
    "enableNotification": false,
    "enableEmailNotify": false,
    "notificationDuration": 6,
    "enableRetry": false,
    "enableRefreshMinRetry": false,
    "email": ""
  }
                
▼ Show full

Sample Request

Curl
Java
Python
Deluge
PowerShell
Copied!
curl --request POST \
  --url https://appdomains/dcapi/config-policies/v2/windows/userMgmt \
  --header 'Accept: application/json' \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52' \
  --header 'Content-Type: application/json' \
  --data '{"configDetails":[{"action":"changePassword","userName":"helpdesk"}],"label":"Reset Helpdesk Password","configType":"computer"}'

Sample Request Body - Reset Password

Reset the password of an existing local account. The action is changePassword and password carries the new value; retainOldPassword keeps the password already saved against the template instead. The existing password of the account is not required on Windows.

Copied!
  {
    "applyAtRefresh": false,
    "applyAlways": false,
    "description": "Created through the Config Policies API.",
    "label": "Reset Helpdesk Password",
    "configType": "computer",
    "applyAtStartupLogon": true,
    "noOfRetries": 2,
    "refreshMinRetry": 1,
    "notificationEnabledDays": 3,
    "enableLogonStartupMinRetry": false,
    "logonStartupMinRetry": 1,
    "configDetails": [
      {
        "password": "N3wP@ssw0rd",
        "passwordHint": "Quarterly rotation",
        "retainOldPassword": false,
        "action": "changePassword",
        "userName": "helpdesk"
      }
    ],
    "enableNotification": false,
    "enableEmailNotify": false,
    "notificationDuration": 6,
    "enableRetry": false,
    "enableRefreshMinRetry": false,
    "email": ""
  }
                
▼ Show full

Response Parameters

- HTTP code 200

Response Body - application/json
JSON Object

Success response returned when the configuration is saved as a reusable template.

Hide Sub-Attributes
templateIdlong

Unique identifier of the created template. Pass it to the Deploy Configuration Template API to deploy this template to targets.

templateNamestring

Name of the created template. It is the label sent in the request.

configTypestring

Type of configuration the template was created for. Allowed values:
computer
user

addedUserstring

Login name of the API user who created the template.

- HTTP code 400

Response Body - application/json
JSON Object

Error response when the request contains invalid or missing required fields.

Hide Sub-Attributes
errorCodelong

Product error code. 50003 = CONFIG_INVALID_INPUT_DATA: configDetails is missing or empty, or the configuration could not be resolved for this endpoint. 20003 = SERVICE_NOT_AVAILABLE: the configuration is deprecated for the requested configType.

errorMsgstring

Localised error message for the error code.

- HTTP code 401

Response Body - application/json
JSON Object
Hide Sub-Attributes
errorCodelong

Unauthorized error code returned when authentication credentials are missing, expired, or invalid (authentication=required)

errorMsgstring

Authentication failure reason

- HTTP code 413

Response Body - application/json
JSON Object

Error response returned when the server does not have enough free disk space to store the configuration files.

Hide Sub-Attributes
errorCodelong

Product error code. 170013 = INTERNAL_SERVER_ERROR: raised by the storage pre-check before the template is saved.

errorMsgstring

Localised error message for the error code.

- HTTP code 429

Response Body - application/json
JSON Object
Hide Sub-Attributes
errorCodelong

Rate limit error code returned when the API call threshold (configured via threshold/duration in security XML) is exceeded; client is locked out for lock-period minutes

errorMsgstring

Rate limit exceeded message with retry guidance

- HTTP code 500

Response Body - application/json
JSON Object

Error response returned when the template could not be saved because of an unexpected server error.

Hide Sub-Attributes
errorCodelong

Product error code. 1003 = INTERNAL_ERROR: the template could not be persisted. 50001 = CONFIG_INTERNAL_ERROR: an internal configuration error occurred while processing the request.

errorMsgstring

Localised error message for the error code.

Response Examples

Sample Response: HTTP 200 - Add User

Success response for deployUserMgmt

Copied!
  {
    "templateName": "deployUserMgmt",
    "templateId": 316,
    "configType": "computer",
    "addedUser": "admin"
  }
                
▼ Show full

Sample Response: HTTP 400 - Add User

Error response for deployUserMgmt

Copied!
  {
    "errorCode": 50003,
    "errorMsg": "Some Input field missing in configuration"
  }
                
▼ Show full

Sample Response: HTTP 200 - Remove User

Success response for deleteUser

Copied!
  {
    "templateName": "deleteUser",
    "templateId": 317,
    "configType": "computer",
    "addedUser": "admin"
  }
                
▼ Show full

Sample Response: HTTP 400 - Remove User

Error response for deleteUser

Copied!
  {
    "errorCode": 50003,
    "errorMsg": "Some Input field missing in configuration"
  }
                
▼ Show full

Sample Response: HTTP 200 - Disable User

Success response for disableUser

Copied!
  {
    "templateName": "disableUser",
    "templateId": 318,
    "configType": "computer",
    "addedUser": "admin"
  }
                
▼ Show full

Sample Response: HTTP 400 - Disable User

Error response for disableUser

Copied!
  {
    "errorCode": 50003,
    "errorMsg": "Some Input field missing in configuration"
  }
                
▼ Show full

Sample Response: HTTP 200 - Enable User

Success response for enableUser

Copied!
  {
    "templateName": "enableUser",
    "templateId": 319,
    "configType": "computer",
    "addedUser": "admin"
  }
                
▼ Show full

Sample Response: HTTP 400 - Enable User

Error response for enableUser

Copied!
  {
    "errorCode": 50003,
    "errorMsg": "Some Input field missing in configuration"
  }
                
▼ Show full

Sample Response: HTTP 200 - Reset Password

Success response for changeUserPassword

Copied!
  {
    "templateName": "changeUserPassword",
    "templateId": 320,
    "configType": "computer",
    "addedUser": "admin"
  }
                
▼ Show full

Sample Response: HTTP 400 - Reset Password

Error response for changeUserPassword - action is changePassword but password is missing

Copied!
  {
    "errorCode": 50003,
    "errorMsg": "Some Input field missing in configuration"
  }
                
▼ Show full

Sample Response: HTTP 401

User is not authorized to create the configuration policy

Copied!
  {
    "errorCode": 1001,
    "errorMsg": "Access denied - You are not allowed to access the requested resource."
  }
                
▼ Show full

Sample Response: HTTP 413

Storage pre-check rejected the request before the template was saved

Copied!
  {
    "errorCode": 170013,
    "errorMsg": "The server machine does not have sufficient disk space. Please free up space and try again."
  }
                
▼ Show full

Sample Response: HTTP 429

Request rejected because the caller exceeded the configured rate limit

Copied!
  {
    "errorCode": "IAM0019",
    "url": "/dcapi/config-policies/v2/windows/userMgmt",
    "errorMsg": "The URL /dcapi/config-policies/v2/windows/userMgmt was called too many times. Please retry after a while."
  }
                
▼ Show full

Sample Response: HTTP 500

Unexpected server error while saving the configuration as a template

Copied!
  {
    "errorCode": 1003,
    "errorMsg": "An Internal Error occurred, try again later."
  }
                
▼ Show full

Duration: 1 minute | Threshold: 30 | Lock period: 5 minutes

Duration - Time window for the threshold.
Threshold - Number of API calls allowed within the specified duration.
Lock Period - Wait time before consecutive API requests.