Help Center/ Elastic Cloud Server/ API Reference/ APIs/ Password Management/ Resetting the Password for Logging In to an ECS with a Few Clicks
Updated on 2025-12-10 GMT+08:00
View PDF
Share

Resetting the Password for Logging In to an ECS with a Few Clicks

Function

This API is used to reset the password offline for the ECS management account (root or Administrator).

Constraints

  • By default, there is no password complexity check that meets security requirements. No error message is displayed after an insecure password is entered.
  • Before using this API, you must install the one-click password reset plug-in. For details about how to download and install one-click password reset plug-in, see Installing the One-Click Password Reset Plug-in on an Individual ECS.
  • You cannot determine whether an ECS supports password reset offline.
  • If the password fails to be reset offline, this API does not report an error.
  • 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 *

-

-

-

URI

PUT /v1/{project_id}/cloudservers/{server_id}/os-reset-password

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.

server_id

Yes

Specifies the ECS ID.

Request

Table 2 describes the request parameters.

Table 2 Request parameters

Parameter

Mandatory

Type

Description

reset-password

Yes

Object

Definition

See Table 3.

Constraints

N/A

Range

N/A

Default Value

N/A
Table 3 reset-password field description

Parameter

Mandatory

Type

Description

is_check_password

No

Boolean

Definition

Specifies whether to check password complexity.

Constraints

N/A

Range

  • true: Check the password complexity.
  • false: Do not check the password complexity.

Default Value

false

new_password

Yes

String

Definition

Specifies the new password for logging in to an ECS.

Constraints

By default, this API does not check password security. To check password security, set is_check_password to true.

Range
  • Contains 8 to 26 characters.
  • Supports the following characters: !@%-_=+[]:./?
  • Cannot contain any of the following characters: ¥—— ·~`#&^,{}*();"'<>|\ $
  • Contains at least three of the following: uppercase letters, lowercase letters, digits, and allowed special characters.
  • Cannot contain username Administrator/root or the username spelled backwards.
  • Cannot contain three consecutive characters in username Administrator

Default Value

N/A

Response

None

Example Request

Reset the password offline for the administrator account (root or Administrator) of a specified ECS. For security purposes, store the passwords in ciphertext in configuration files or environment variables.

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

{
	"reset-password": {
		"new_password": "$ADMIN_PASS"
	}
}

Example Response

None

Returned Values

See Returned Values for General Requests.

Error Codes

See Error Codes.

Parent topic: Password Management