Help Center/Elastic Cloud Server/API Reference/APIs/Batch Operations/Resetting the Passwords for Logging In to ECSs in a Batch
Updated on 2026-03-19 GMT+08:00
View PDF
Share

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

Definition

Specifies the project ID.

For details about how to obtain the ID, see Obtaining a Project ID.

Constraints

N/A

Range

N/A

Default Value

N/A

Request

Table 2 describes the request parameters.

Table 2 Request parameters

Parameter

Type

Mandatory

Description

new_password

String

Yes

Definition

Specifies the new password.

Constraints

This field is mandatory only if dry_run is set to false.

Range

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.

Default Value

N/A

dry_run

Boolean

No

Definition

Specifies whether the system checks the request. If this parameter is set to true, the system checks the request, but no password will be reset.

Constraints

N/A

Range

  • true: The system checks the request. Check items include mandatory parameters, request format, and constraints.
    • If the check fails, the system returns an error.
    • If the check is successful, the system returns a normal response.
  • false: The system sends the request without checking the request body.

Default Value

false

servers

Array of objects

Yes

Definition

Specifies the IDs of the target ECSs. For details, see Table 3.

Constraints

N/A

Range

N/A

Default Value

N/A

Table 3 servers field description

Parameter

Type

Mandatory

Description

id

String

Yes

Definition

Specifies the ECS ID.

Constraints

N/A

Range

N/A

Default Value

N/A

Response

Table 4 describes the response parameters.

Table 4 Response parameters

Parameter

Type

Description

response

Array of objects

Definition

Specifies the response returned after a request is delivered. For details, see Table 1.

Range

N/A

Table 5 response field description

Parameter

Type

Description

id

String

Definition

Specifies the ID of the ECS on which the operation is successful.

Range

N/A

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"                      
                   }                
                 ] 
}

Returned Values

See Returned Values for General Requests.

Error Codes

See Error Codes.

Parent topic:Batch Operations