--- title: User Passwords description: The password management endpoints provide functions that enable the following operations on a specified user: component: pingone-api page_id: pingone-api:platform:users/user-passwords canonical_url: https://developer.pingidentity.com/pingone-api/platform/users/user-passwords.html section_ids: password-state-data-model: Password state data model password-status-states: Password status states --- # User Passwords The password management endpoints provide functions that enable the following operations on a specified user: * Get a user's password state * Validate a user's password * Set a user's password * Update a user's password * Unlock a user's password * Recover a forgotten password | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Users who authenticate with an authoritative identity provider cannot perform any self-service actions on passwords. Their `user.identityProvider.id` attribute is not `null` and their `user.identityProvider.type` attribute is not `PING_ONE`. These actions include:* [Read Password State](user-passwords/read-password-state.html) * [POST Password Check](user-passwords/password-check.html) * [PUT Update Password (Self)](user-passwords/update-password-self.html)Attempting to do so returns a REQUEST\_FAILED exception. | ## Password state data model | Property | Type | Required? | Mutable? | Description | | ---------------------------- | -------- | --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `environment.id` | String | Required | Mutable | Specifies the ID of the environment resource referenced by this relationship. | | `currentPassword` | String | Required | Mutable | The current password to be verified before the new password is set. Required for self-change when the user already has a password (the user whose password is being changed is the same as the actor in the access token). | | `lastChangedAt` | DateTime | N/A | Read-only | The time the password was last changed. This property is not returned if the user does not have a password. | | `newPassword` | String | Optional | Mutable | The new password (must satisfy all requirements). | | `passwordPolicy.id` | String | N/A | Read-only | Specifies the ID of the password policy resource referenced by this relationship. | | `secondsUntilUnlock` | Integer | N/A | Read-only | Specifies the number of seconds before the password may be used again after a lock out. If absent, the password must be reset by an administrator before it may be used again after a lockout. | | `status` | String | N/A | Read-only | Specifies the current status of the password. Options are `OK`, `NO_PASSWORD`, `PASSWORD_EXPIRED`, `PASSWORD_LOCKED_OUT`, `MUST_CHANGE_PASSWORD`, and `EXTERNAL`. For more information, refer to the "Password status states" table below. | | `user.id` | String | Required | Mutable | Specifies the ID of the user resource referenced by this relationship. | | `warnings.expires` | Object | N/A | Read-only | Warns that the password will expire on the specified date and time. The warning will only display if the password will expire in less than 21 days. | | `warnings.failuresRemaining` | Object | N/A | Read-only | Warns that the password has been checked unsuccessfully and the user will be locked out after the indicated number of further unsuccessful attempts. | | `warnings.noChangeUntil` | Object | N/A | Read-only | Warns that the password was recently self-changed and cannot be self-changed again until the specified date and time. | | | | | - | -------------------------------------------------------------------------------------------------------------------------------- | | | For information about password policy data model properties, refer to [Password policies data model](../password-policies.html). | ## Password status states | Password state | Description | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `NO_PASSWORD` | Specifies that no password has been set. It also indicates that the user does not use a password for authentication. | | `OK` | Specifies that a password has been set and can be used for login actions. | | `PASSWORD_EXPIRED` | Specifies that the current password has expired and cannot be used for login actions. | | `MUST_CHANGE_PASSWORD` | Specifies that the user's password has been changed by the administrator and must be reset by the user before the next login action. | | `PASSWORD_LOCKED_OUT` | Specifies that a password is temporarily locked out as a result of too many invalid login attempts. It cannot be used for login actions. | | `EXTERNAL` | Specifies that a password is managed in a remote directory, not in PingOne. If the referenced gateway in `password.gateway` does not allow password changes (`allowPasswordChanges=false`), then password changes are blocked and links for `password.forgot` and `password.reset` are not included. |