Skip to main content

Modify Password

PATCH 
/auth/v1/user/password

API Description​

Modify the current user's password, requires sending a verification code via the Reauthenticate API for secondary verification before execution. This operation is used for users to modify their own login password, requiring secondary verification to ensure security.

Features​

  • Modify current user's login password
  • Requires verification code from reauthenticate API for secondary verification
  • Supports password strength validation
  • Old password becomes invalid immediately after modification
  • Automatically logout other device logins

Input Requirements​

Required Parameters​

  • Authorization: Current logged-in user's access_token (required, Bearer format)
  • client_id: Client ID corresponding to the application (optional, defaults to environment ID)
  • x-device-id: Device ID (optional, current logged-in device ID)

Request Body Parameters​

  • old_password: Old password (optional, if user has password)
  • new_password: New password (required, 8-64 characters, including uppercase and lowercase letters, numbers, special characters)
  • confirm_password: Confirm password (optional, for frontend validation)
  • verify_code: Verification code (required, the code sent to user's phone or email via Reauthenticate API)

Prerequisites​

  • User must be logged in and hold valid access_token
  • Must send verification code via Reauthenticate API
  • Verification code valid for 300 seconds (5 minutes)
  • New password must meet password strength requirements
  • If user already has password, need to provide old password for verification

Output Description​

Successful Response​

  • Returns empty object, indicating password modification successful

Request Examples​

Modify Password Request Example (with old password)​

PATCH /auth/v1/user/password
Authorization: Bearer your_access_token
Content-Type: application/json

{
  "old_password": "your-password",
  "new_password": "your-new-password",
  "confirm_password": "your-new-password",
  "verify_code": "101894"
}

Modify Password Request Example (no old password, first time setting)​

PATCH /auth/v1/user/password
Authorization: Bearer your_access_token
Content-Type: application/json

{
  "new_password": "your-password",
  "confirm_password": "your-password",
  "verify_code": "101894"
}

Response Examples​

Modification Success Response​

{}

Old Password Error Response​

{
  "error": "invalid_password",
  "error_code": 4003,
  "error_description": "Old password error, please re-enter"
}

Password Strength Insufficient Response​

{
  "error": "weak_password",
  "error_code": 4005,
  "error_description": "Password strength insufficient, please use combination of uppercase and lowercase letters, numbers and special characters"
}

Usage Flow​

1. Initiate Reauthentication​

  • Call Reauthenticate API to send verification code
  • Choose SMS or email method to receive verification code

2. User Receives Verification Code​

  • User checks verification code in phone or email
  • Verification code valid for 300 seconds (5 minutes)

3. Verify Password Rules​

  • Frontend validates new password strength
  • Confirm password consistency
  • Check password history

4. Execute Modification​

  • Call this API to modify password
  • Pass verify_code (the verification code received by user) in request body for secondary verification

5. Handle Result​

  • Prompt user on successful modification
  • Display specific reason on error
  • Automatically logout other device logins

Key Characteristics​

Security​

  • Requires verification code secondary verification
  • Automatic password strength detection
  • Prevents password reuse
  • Automatically logout other devices

Password Rules​

  • Length: 8-64 characters
  • Must include uppercase and lowercase letters
  • Must include numbers
  • Must include special characters
  • Cannot be same as old password

Notes​

Security Recommendations​

  • Recommend regular password changes
  • Avoid using common password combinations
  • Don't use same password as other websites
  • Recommend enabling two-factor authentication

Password Strength Requirements​

  • At least 8 characters, maximum 64 characters
  • Include uppercase letters, lowercase letters, numbers, special characters
  • Cannot contain username or email address
  • Cannot use consecutive or repeated characters

Impact Scope​

  • Takes effect immediately after modification
  • Other device logins automatically invalidated
  • Need to re-login all devices
  • Third-party logins not affected

Common Error Scenarios​

  • Verification code expired: Prompt user to resend verification code
  • Old password error: Display specific error message
  • Password strength insufficient: Provide password rule explanation
  • Network exception: Retry mechanism

Request​

Responses​

A successful response.

Response Headers