User passwords


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

User password management API operations

The password management endpoints support the following operations:

For hands-on experience with the users API endpoints, click the Run in Postman button below to download a Postman collection that you can import and open in your local Postman application.

Get the password state

You can check the current status of a user’s password to determine whether the password is active or expired. You can also check the number of password-attempt failures remaining before the account is locked.

The following sample shows the GET /environments/{environmentId}/users/{userId}/password returns information about the user’s password state.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/password" \
-H "Authorization: Bearer jwtToken"

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca"
        },
        "user": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af"
        },
        "passwordPolicy": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/passwordPolicies/5da98f13-ad62-4234-86d3-01018f6ef0ad"
        },
        "password.validate": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
        },
        "password.reset": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
        },
        "password.set": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
        },
        "password.recover": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
        }
    },
    "environment": {
        "id": "5da98f13-ad62-4234-ba04-2b6e2e85c8ca"
    },
    "user": {
        "id": "c3042000-188f-4bc7-a269-dee1602cf7af"
    },
    "passwordPolicy": {
        "id": "5da98f13-ad62-4234-86d3-01018f6ef0ad"
    },
    "status": "NO_PASSWORD",
    "lastChangedAt": "2019-01-08T20:18:31.264Z"
}

Check a user’s password

You can check a user’s password to verify its current state. The result of a password validation check returns one of the following values for the status property:

  • NO_PASSWORD

    No password has been set for the account.

  • OK

    The password submitted in the request matches the user’s stored password.

  • PASSWORD_EXPIRED

    The current password has expired and cannot be used to log in.

  • PASSWORD_LOCKED_OUT

    The password is locked because of too many failed password attempts. It cannot be used to log in.

  • MUST_CHANGE_PASSWORD

    The password was changed by an administrator. It must be reset (changed) by the user before it can be used to log in.

The following sample shows the POST /environments/{environmentId}/users/{userId}/password operation to check the password attribute value provided in the request body against the current password. This operation uses the application/vnd.pingidentity.password.check+json custom content type in the request header.

curl -X POST "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/password" \
-H "Content-type: application/vnd.pingidentity.password.check+json" \
-H "Authorization: Bearer jwtToken" \
-d "{
  "password": "<password>"
}"

The password value in the request body is checked against the user’s current password. If the password is checked successfully, and the password status is OK, MUST_CHANGE_PASSWORD, or PASSWORD_EXPIRED, the response returns a 200 OK message. If the password status is NO_PASSWORD or PASSWORD_LOCKED_OUT, the response returns a 400 BAD REQUEST message.

Unlock password

The POST /environments/{environmentId}/users/{userId}/password endpoint is called by an administrator or an application to unlock a user’s password. This operation uses the application/vnd.pingidentity.password.unlock custom media type as the content type in the request header.

The following sample shows the POST /environments/{environmentId}/users/{userId}/password operation to unlock a password for the user identified by the user ID and environment ID.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/password" \
-H 'Content-type: application/vnd.pingidentity.password.unlock' \
-H 'Authorization: Bearer jwtToken'

This POST request does not require any attribute values in the request body. It returns a 200 OK message when successful and generates a PASSWORD.UNLOCKED event.

Recover password

The POST /environments/{environmentId}/users/{userId}/password endpoint is called to recover a forgotten password. It sends a one-time-password (OTP) that is used to reset the password. The OTP is a randomly generated eight-character alphanumeric string sent to the user’s email address, and the code is valid for five minutes. This operation uses the application/vnd.pingidentity.password.sendRecoveryCode+json custom media type as the content type in the request header.

The following sample shows the POST /environments/{environmentId}/users/{userId}/password operation to recover a password for the user identified by the environment ID and user ID.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/password" \
-H 'Content-type: application/vnd.pingidentity.password.sendRecoveryCode+json' \
-H 'Authorization: Bearer jwtToken'

If the user exceeds the maximum number of invalid attempts to recover the password while using the recovery OTP, the password status is changed to the PASSWORD_LOCKED_OUT. The POST /environments/{environmentId}/users/{userId}/password endpoint is also used to reset the locked-out password using a recovery code. This operation uses the application/vnd.pingidentity.password.recover+json custom media type as the content type in the request header, and it requires the recoveryCode and the newPassword attributes in the request body.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/password" \
-H 'Content-type: application/vnd.pingidentity.password.recover+json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "recoveryCode": "<code>",
  "newPassword": "VerySecure123!"
}'

Update a user’s password

Password update requests are structured differently based on whether the password update is a self change or an administrative change. The PUT /environments/{environmentId}/users/{userId}/password endpoint is called in both cases, but the request body for the self-change operation requires a value for the currentPassword attribute while the administrative-change operation does not. Both operations use application/vnd.pingidentity.password.reset+json as the content type in the request header.

Self-change password update

The following sample shows the PUT /environments/{environmentId}/users/{userId}/password operation to execute a self-change reset of the password identified by the user ID and environment ID.

curl -X "PUT" "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/password" \
-H 'Content-type: application/vnd.pingidentity.password.reset+json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "currentPassword": "changeme",
  "newPassword": "difPassword123!"
}'

In the request body, the currentPassword value specifies the existing password, and newPassword specifies the value of the new password assigned to this user. Note that the new password is validated against the current password policy. For a successful self-change update, the status attribute value is changed to OK.

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca"
        },
        "user": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af"
        },
        "passwordPolicy": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/passwordPolicies/5da98f13-ad62-4234-86d3-01018f6ef0ad"
        },
        "password.validate": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
        },
        "password.reset": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
        },
        "password.set": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
        },
        "password.recover": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
        }
    },
    "environment": {
        "id": "5da98f13-ad62-4234-ba04-2b6e2e85c8ca"
    },
    "user": {
        "id": "c3042000-188f-4bc7-a269-dee1602cf7af"
    },
    "passwordPolicy": {
        "id": "5da98f13-ad62-4234-86d3-01018f6ef0ad"
    },
    "status": "OK",
    "lastChangedAt": "2019-01-08T20:18:31.264Z"
}

Administrative-change password update

The following sample shows the PUT /environments/{environmentId}/users/{userId}/password operation to execute an administrative-change reset of the password identified by the user ID and environment ID.

curl -X "PUT" "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/password" \
-H 'Content-type: application/vnd.pingidentity.password.reset+json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "newPassword": "Changeme123!"
}'

In the request body, the newPassword attribute specifies the new password assigned to this user by the administrator. For a successful administrator-change update, the status attribute value is changed to MUST_CHANGE_PASSWORD. Note that this assigned temporary password is not validated against the current password policy.

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca"
        },
        "user": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af"
        },
        "passwordPolicy": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/passwordPolicies/5da98f13-ad62-4234-86d3-01018f6ef0ad"
        },
        "password.validate": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
        },
        "password.reset": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
        },
        "password.set": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
        },
        "password.recover": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
        }
    },
    "environment": {
        "id": "ec814a6f-4e7e-45aa-92ea-c670f7190352"
    },
    "user": {
        "id": "8b015deb-073d-4c25-a51d-99768b01567d"
    },
    "passwordPolicy": {
        "id": "ec814a6f-4e7e-45aa-86d3-01018f6ef0ad"
    },
    "status": "MUST_CHANGE_PASSWORD",
    "lastChanged": "2018-06-15T17:12:30.087Z"
}

Set password

The PUT /environments/{environmentId}/users/{userId}/password endpoint is also called to set a user’s password. This operation uses the application/vnd.pingidentity.password.set+json custom media type as the content type in the request header.

The following sample shows the PUT /environments/{environmentId}/users/{userId}/password operation to set a password for the user identified by the user ID and environment ID.

curl -X "PUT" "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/password" \
-H 'Content-type: application/vnd.pingidentity.password.set+json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "forceChange": "true",
  "value": "Changeme123!"
}'

In the request body, the forceChange value specifies whether the user must change the current password on the next login. If forceChange is set to true, the status attribute value is changed to MUST_CHANGE_PASSWORD. If forceChange is omitted from the request, its value is set to false by default, and the status attribute value is set to OK.

The value attribute specifies the value of the new password assigned to this user. The password can be either cleartext or pre-encoded. Cleartext passwords are evaluated against the current password policy. Pre-encoded passwords are not evaluated against the password policy, and they are specified by the name of the encoding scheme followed by an encoded representation of the password (for example, {SSHA512}df6b9fb15cfdbb7527be5a8a6e39f39e572c8ddb943fbc79a943438e9d3d85ebfc2ccf9e0eccd9346026c0b6876e0e01556fe56f135582c05fbdbb505d46755a). PingOne supports the following encoding schemes:

Scheme Scheme identifier
bcrypt {BCRYPT}
scrypt {SCRYPT}
salted SHA1 {SSHA}
salted SHA256 {SSHA256}
salted SHA384 {SSHA384}
salted SHA512 {SSHA512}

If a cleartext password is provided and it does not meet the password quality requirements, the following error is returned.

400 BAD REQUEST
{  
   "id":"6c796712-0f16-4062-815a-e0a92f4a2143",
   "code":"INVALID_DATA",
   "message":"The data provided was invalid.",
   "details":[  
      {  
         "code":"INVALID_VALUE",
         "target":"value",
         "message":"The password did not satisfy password policy requirements",
         "innerError":{
           "unsatisfiedRequirements":["excludesProfileData", "length"]
         }
      }
   ]
}

The password policy attribute names returned in the unsatisfiedRequirements array identify the specific password policy requirements that the submitted password does not meet.