PingOne Platform APIs

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:

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 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.