Help Center/ Elastic Cloud Server/ API Reference/ APIs/ Batch Operations/ Resetting the Passwords for Logging In to ECSs in a Batch

Updated on 2025-12-10 GMT+08:00

View PDF

Resetting the Passwords for Logging In to ECSs in a Batch

Function

This API is used to reset the passwords of the ECS management account (root or Administrator) in a batch.

Constraints

Before using this API, you must install the password reset plug-in. For instructions about how to download and install the password reset plug-in, see "Installing the One-Click Password Reset Plug-in on an ECS" in the Elastic Cloud Server User Guide.
After the request for resetting the password is delivered, this API does not report an error if executing the script failed.
A new password takes effect after the ECS is started or restarted.

Debugging

You can debug this API in API Explorer.

Authorization

Each account has all of the permissions required to call all APIs, but IAM users must have the required permissions specifically assigned.

If you are using role/policy-based authorization, see the required permissions in Permissions and Supported Actions.
If you are using identity policy-based authorization, the permissions listed below are required.

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependencies
ecs:cloudServers:resetServerPwd	write	instance *	g:ResourceTag/<tag-key> g:EnterpriseProjectId	-	-

URI

PUT /v1/{project_id}/cloudservers/os-reset-passwords

Table 1 lists the URI parameters.

**Table 1** Parameter description
Parameter	Mandatory	Description
project_id	Yes	Specifies the project ID. For details about how to obtain the ID, see Obtaining a Project ID.

Request

Table 2 describes the request parameters.

**Table 2** Request parameters
Parameter	Type	Mandatory	Description
new_password	String	Yes	Specifies the new password. This field is mandatory only if dry_run is set to false. A new password must comply with the following rules: The password must contain 8 to 26 characters. Contains at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters (!@%-_=+[]:./?). Cannot contain the username or the username spelled backwards. For a Windows ECS, the password cannot contain the username, the username spelled backwards, or more than two consecutive characters in the username.
dry_run	Boolean	No	Specifies whether to check the request and reset ECS passwords. true: indicates that only the password reset request is sent and the passwords for logging in to the ECSs will not be reset. Check items include mandatory parameters, request format, and service restrictions. If the check fails, the system returns an error. If the check result is as expected, the system properly responds. false: indicates that the password reset request is sent and the passwords for logging in to the ECSs will be reset if the check result is as expected. The default value is false.
servers	Array of objects	Yes	Specifies the IDs of the target ECSs. For details, see Table 3.

**Table 3** **servers** field description
Parameter	Type	Mandatory	Description
id	String	Yes	Specifies the ECS ID.

Response

Table 4 describes the response parameters.

**Table 4** Response parameters
Parameter	Type	Description
response	Array of objects	Specifies the response returned after a request is delivered. For details, see Table 1.

**Table 5** **response** field description
Parameter	Type	Description
id	String	Specifies the ID of the ECS on which the operation is successful.

Example Request

Batch reset the passwords of the ECSs whose IDs are 1bd0eb17-4466-4c15-a9ce-87727ad311b5 and fd6b6e9d-64a1-40fa-b7dc-f491be42fdd2. For security purposes, store the passwords in ciphertext in configuration files or environment variables.

PUT https://{endpoint}/v1/{project_id}/cloudservers/os-reset-passwords

{
    "new_password": "$ADMIN_PASS",
    "dry_run": true,
    "servers": [
                {
                  "id":"1bd0eb17-4466-4c15-a9ce-87727ad311b5"  
                },
                {
                  "id":"fd6b6e9d-64a1-40fa-b7dc-f491be42fdd2" 
                }
               ]
}

Example Response

See Responses (Batch Requests).

{      
    "response": [                   
                  {                     
                    "id": "616fb98f-46ca-475e-917e-2563e5a8cd19"                      
                   },                   
                  {                     
                    "id": "516fb98f-46ca-475e-917e-2563e5a8cd12"                      
                   }                
                 ] 
}