User Accounts

The user account management endpoint provides functionality to unlock a user account. For information about how to configure account lockout for MFA actions, refer to MFA Settings.

Account state data model

Property Type Required Mutable Description

Property	Type	Required	Mutable	Description
`account.canAuthenticate`	Boolean	Required	Mutable	Indicates whether the user can authenticate. If the value is set to `false`, the account is locked or the user is disabled, and unless specified otherwise by the administrative configuration, the user will be unable to authenticate.
`account.lockedAt`	Date	N/A	Read-only	The date-time the specified user account was locked. This property might be absent if the account is unlocked or if the account was locked out automatically by failed password attempts.
`account.secondsUntilUnlock`	Integer	Optional	Read-only	The number of seconds until the user’s account is unlocked. This property is absent if the account is unlocked, or if it will not automatically unlock (and must be unlocked by an administrator).
`account.status`	String	Required	Mutable	The account locked state. Options are `LOCKED` and `OK`.
`account.unlockAt`	Date	Optional	Mutable	The time the specified user account will be unlocked. This property is absent if the account is unlocked, or if it will not automatically unlock (and must be unlocked by an administrator).

account.canAuthenticate

Boolean

Required

Mutable

Indicates whether the user can authenticate. If the value is set to false, the account is locked or the user is disabled, and unless specified otherwise by the administrative configuration, the user will be unable to authenticate.

account.lockedAt

Date

N/A

Read-only

The date-time the specified user account was locked. This property might be absent if the account is unlocked or if the account was locked out automatically by failed password attempts.

account.secondsUntilUnlock

Integer

Optional

Read-only

The number of seconds until the user’s account is unlocked. This property is absent if the account is unlocked, or if it will not automatically unlock (and must be unlocked by an administrator).

account.status

String

Required

Mutable

The account locked state. Options are LOCKED and OK.

account.unlockAt

Date

Optional

Mutable

The time the specified user account will be unlocked. This property is absent if the account is unlocked, or if it will not automatically unlock (and must be unlocked by an administrator).

User account errors

In addition to the general error codes, user account operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

HTTP status	Top‑level code	Detail code	When it happens and what the response contains
400	`REQUEST_FAILED`	`CONSTRAINT_VIOLATION`	Message: `The request could not be completed. There was an issue processing the request.` When and details When: A `POST` Unlock User Account request targets a user whose `lifecycle.status` is `INVITED` Details: `Operation not allowed for users with lifecycle.status INVITED`
400	`INVALID_REQUEST`	`INVALID_VALUE` or None	Message: `The request could not be completed. The request was malformed or invalid.` When and details When: A `POST` Lock User Account request body cannot be deserialized, for example an `unlockAt` value that is not a valid date-time Details: For a JSON field conversion error, the detail is `Invalid value for attribute.` with target `unlockAt`. Otherwise no detail is returned.
403	`ACCESS_FAILED`	None	Message: `The actor attempting to perform the request is not authorized.` When and details When: The actor lacks the `dir:unlock:userAccount` permission (`POST` with the `application/vnd.pingidentity.account.unlock+json` content type) or the `dir:lock:userAccount` permission (`POST` with the `application/vnd.pingidentity.account.lock+json` content type), the actor is not authorized for the environment or the target user’s population, or the actor attempts to lock or unlock their own account Details: None.
404	`NOT_FOUND`	None	Message: `The request could not be completed. The requested resource was not found.` When and details When: The user ID or environment ID in the request URL does not exist Details: None.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A POST Unlock User Account request targets a user whose lifecycle.status is INVITED

Details: Operation not allowed for users with lifecycle.status INVITED

400

INVALID_REQUEST

INVALID_VALUE or None

Message: The request could not be completed. The request was malformed or invalid.

When and details

When: A POST Lock User Account request body cannot be deserialized, for example an unlockAt value that is not a valid date-time

Details: For a JSON field conversion error, the detail is Invalid value for attribute. with target unlockAt. Otherwise no detail is returned.

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the dir:unlock:userAccount permission (POST with the application/vnd.pingidentity.account.unlock+json content type) or the dir:lock:userAccount permission (POST with the application/vnd.pingidentity.account.lock+json content type), the actor is not authorized for the environment or the target user’s population, or the actor attempts to lock or unlock their own account

Details: None.

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: The user ID or environment ID in the request URL does not exist

Details: None.

PingOne Platform APIs

User Accounts

Account state data model

User account errors