Skip to main content

Password Change

The password change process is a vital security feature that allows users to update their login credentials. This process ensures that users can maintain control over their account security by regularly updating their passwords or immediately changing them if they suspect any unauthorized access. Including a password change option on the user profile page enhances security, provides convenience, and empowers users to proactively manage their account safety. By enabling easy access to this feature, you promote a safer and more user-friendly environment.

When to use this API​

Use PUT /password-srv/password when the user is already authenticated and wants to replace their current password with a new one.

Use this API for​

  • User-initiated password change from profile/security settings.
  • Security-driven password rotation while the user is logged in.
  • Flows where the current password must be verified (old_password) before saving a new one.

Do not use this API for​

  • Forgot-password flow for unauthenticated users. Use reset password flow APIs instead.
  • First-login forced password change during authentication precheck. Use precheck/continue in password_change condition.
  • Password setup for users who never had a password (for example passwordless/social onboarding). Use POST /password-srv/password.

Supported and Unsupported Scenarios​

Supported​

  • Authenticated user changes password with old_password, new_password, and confirm_password.
  • Request can identify the user with either sub or identityId (integration-dependent).
  • Policy and password-history validation are enforced on new_password.

Unsupported / expected failures​

  • Missing identifier (sub and identityId both absent) results in validation failure.
  • Using wrong request keys on this endpoint, such as password instead of new_password.
  • Incorrect old_password.
  • Reusing recent password (history policy).
  • New password violating configured password policy. Exact acceptance/rejection depends on tenant policy configuration.

Minimal Flow Context​

PUT /password-srv/password is one step in the broader password lifecycle.

Use this API only when the user is already authenticated and wants to replace their current password.

For adjacent password flows, use these guides/APIs:

APIDescriptionLink
Change Password (authenticated user)Changes an existing password for a logged-in user.Link to API
Set PasswordSets a password for users who do not currently have one (for example passwordless/social users).Link to API
Change Password on Next LoginUsed in authentication precheck continuation when password_change is enforced.Link to API

Quick Test (cURL)​

curl --location --request PUT 'https://domain/password-srv/password' \
  -H 'Authorization: Bearer <user_access_token>' \
  -H 'Content-Type: application/json' \
  --data '{
    "sub": "6f9a2ea0-6ed7-4889-bf89-01c433e9cd15",
    "old_password": "Test#12345",
    "new_password": "Test#12345Next!",
    "confirm_password": "Test#12345Next!"
  }'

The API returns success when the password is changed.

Validated Request Contract (PUT /password-srv/password)​

The Change Password API requires the following keys in the request body:

  • sub (or identityId based on integration flow)
  • old_password
  • new_password
  • confirm_password

Important: For PUT /password-srv/password, the key must be new_password (not password).

Additional notes:

  • Provide one user identifier: sub or identityId based on your integration flow.
  • Provide exactly one identifier (sub or identityId), and do not send both in the same request.
  • confirm_password must match new_password.
  • old_password must match the currently active password.

Example: valid payload​

{
  "sub": "6f9a2ea0-6ed7-4889-bf89-01c433e9cd15",
  "old_password": "Test#12345New!",
  "new_password": "Test#12345Next!",
  "confirm_password": "Test#12345Next!"
}

Example: invalid payload key​

{
  "sub": "6f9a2ea0-6ed7-4889-bf89-01c433e9cd15",
  "old_password": "Test#12345New!",
  "password": "Test#12345Next!",
  "confirm_password": "Test#12345Next!"
}

The request above is rejected because new_password is missing.

Example: valid payload (identityId flow)​

{
  "identityId": "45b97919-8445-427a-a497-58e36303766a",
  "old_password": "Test#12345New!",
  "new_password": "Test#12345Next!",
  "confirm_password": "Test#12345Next!"
}

Handling of Error Messages​

Please ensure that you handle error messages for pwned passwords and password policy mismatches. Also ensure that all required variables are provided. Please find error responses in the FAQ

Frequently Observed Error Codes (Change Password)​

CodeStatusError Message (example)Typical Cause
VER_0005417identityId or sub or old_password or new_password or confirm_password in payload must not be emptyMissing required keys or wrong key names (for example using password instead of new_password).
VAC1148417new_password and confirm_password not matchingconfirm_password does not match new_password.
VER_0012400Old password is incorrectold_password does not match the user's current password.
VER_0118400Password not match with policynew_password violates the configured password policy (length, complexity, etc.).
VER_0119400the password is reused, please use a different passwordnew_password is already used recently and blocked by password history rules.
401401UnauthorizedMissing, expired, or invalid access token.

Note: Policy-related responses (VER_0118, VER_0119) are tenant-policy dependent and may vary by instance configuration.

Response Handling and Next Steps​

  • 200 success means password change is completed.
  • Apply client handling according to your logout strategy (logout_option).
  • For ALL, expect active sessions to be logged out; redirect user to login and request fresh authentication.
  • For NONE, the session may continue; still inform the user that password was updated.
  • For validation errors (400/417), show actionable UI feedback and let user correct the input.

Need help implementing this?​

Please contact us on our Support Portal.