Users


Users

A user resource is a unique identity within PingOne that interacts with the applications and services in the environment to which the user is assigned. The users service implements directory functions to create, read, update, delete, and search for user resources. Users are associated with an environment and a population.

The examples below show common actions to find and manage users, user passwords, and user role assignments. You need the Identity Data Admin role to perform operations on users resources.

Filtering result data

You can filter result data by applying a SCIM filtering expression to the GET request URL. For large collections, a filtering expression appended to the query returns a targeted, more useful data set. For example, this URL-encoded SCIM filter returns users with a last name of “Smith” and a first name that starts with the letter “W”:

https://api.pingone.com/v1/environments/b7372995-824b-44ff-99f8-ab151dac3263/users?filter=name.family%20eq%20%22Smith%22%20and%20name.given%20sw%20%22W%22"

These SCIM operators can be applied to the following attributes:

  • eq (equals)

    Supported attributes: username, name.family, name.given, email, mobilePhone, population.id

  • sw (starts with)

    Supported attributes: username, name.family, name.given, email, mobilePhone

  • and (logical AND)

    Logical AND for building compound expressions in which both expressions are true.

  • or (logical OR)

    Logical OR for building compound expressions if either expression is true.

Note: These SCIM operators are not supported: ne (not equal), co (contains), ew (ends with), pr (present, is a non-empty or non-null value), gt (greater than), ge (greater than or equal to), lt (less than), le (less than or equal to), not (logical NOT).

For more information about SCIM syntax and operators, see Conventions.

Users API operations

The users endpoints support the following operations:

Users population endpoints

Users role assignments endpoints

Users password endpoints

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.

Users data model

Property Description
accountId A string that specifies the user’s account ID, which is optional. This may be explicitly set to null when updating a user to unset it. This attribute is organization-specific and has no special meaning within the PingOne platform.
address.countryCode A string that specifies the country name component. When specified, the value must be in ISO 3166-1 “alpha-2” code format [ISO3166]. For example, the country codes for the United States and Sweden are “US” and “SE”, respectively.
address.locality A string that specifies the city or locality component of the address.
address.postalCode A string that specifies the zip code or postal code component of the address.
address.region A string that specifies the state or region component of the address.
address.streetAddress A string that specifies the full street address component, which may include house number, street name, P.O. box, and multi-line extended street address information. This attribute may contain newlines.
createdAt The time the resource was created.
email A string that specifies the user’s email address, which must be provided and valid.
enabled A read-only boolean attribute that specifies whether the user is enabled. This attribute is set to ‘true’ by default when the user is created.
environment.id A string that specifies the environment resource’s unique identifier associated with the user.
externalId A string that specifies an identifier for the user resource as defined by the provisioning client. This is optional. This may be explicitly set to null when updating a user to unset it. The externalId attribute may simplify the correlation of the user in PingOne with the user’s account in another system of record. The platform does not use this attribute directly in any way, but it is used by Ping Identity’s Data Sync product.
id A string that specifies the user resource’s unique identifier.
lifecycle.status A string that specifies information about the account lifecycle. Options for status are ACCOUNT_OK and VERIFICATION_REQUIRED. This property value is only allowed to be set when importing a user to set the initial account status. If the initial status is set to VERIFICATION_REQUIRED and an email address is provided, a verification email is sent.
locale A string that specifies the user’s default location, which is optional. This may be explicitly set to null when updating a user to unset it. This is used for purposes of localizing such items as currency, date time format, or numerical representations. If provided, a valid value is a language tag as defined in RFC 5646. The following are example tags: fr, en-US, es-419, az-Arab, man-Nkoo-GN.
mfaEnabled A read-only boolean attribute that specifies whether multi-factor authentication is enabled. This attribute is set to ‘false’ by default when the user is created.
mobilePhone A string that specifies the user’s mobile phone number, which is optional. This might also match the primaryPhone attribute. This may be explicitly set to null when updating a user to unset it. If provided, it must consist of a leading plus sign, 1 to 3-digit country code, dot separator, 4 to 14-digit phone number, and optional 1 to 8-digit extension (for example, +1.3034682900x1234).
name.family A string that specifies the family name of the user, or Last in most Western languages (for example, ‘Jensen’ given the full name ‘Ms. Barbara J Jensen, III’). This may be explicitly set to null when updating a name to unset it. Valid characters consists of any Unicode letter, mark (for example, accent, umlaut), space, dot, apostrophe, or hyphen. It can have a length of no more than 256 characters.
name.formatted A string that specifies the fully formatted name of the user (for example ‘Ms. Barbara J Jensen, III’). This can be explicitly set to null when updating a name to unset it.
name.given A string that specifies the given name of the user, or First in most Western languages (for example, ‘Barbara’ given the full name ‘Ms. Barbara J Jensen, III’). This may be explicitly set to null when updating a name to unset it. Valid characters consists of any Unicode letter, mark (for example, accent, umlaut), space, dot, apostrophe, or hyphen. It can have a length of no more than 256 characters.
name.honorificPrefix A string that specifies the honorific prefix(es) of the user, or title in most Western languages (for example, ‘Ms.’ given the full name ‘Ms. Barbara Jane Jensen, III’). This can be explicitly set to null when updating a name to unset it.
name.honorificSuffix A string that specifies the honorific suffix(es) of the user, or suffix in most Western languages (for example, ‘III’ given the full name ‘Ms. Barbara Jane Jensen, III’). This can be explicitly set to null when updating a name to unset it.
name.middle A string that specifies the the middle name(s) of the user (for exmple, ‘Jane’ given the full name ‘Ms. Barbara Jane Jensen, III’). This can be explicitly set to null when updating a name to unset it. Valid characters consists of any Unicode letter, mark (for example, accent, umlaut), space, dot, apostrophe, or hyphen. It can have a length of no more than 256 characters.
nickname A string that specifies the user’s nickname, which is optional. This can be explicitly set to null when updating a user to unset it. Valid characters consists of any Unicode letter, mark (for example, accent, umlaut), space, dot, apostrophe, or hyphen. It can have a length of no more than 256 characters.
photo.href A string that specifies the URI that is a uniform resource locator (as defined in Section 1.1.3 of RFC 3986) that points to a resource location representing the user’s image. This can be removed from a user by setting the photo attribute to null. If provided, the resource must be a file (for example, a GIF, JPEG, or PNG image file) rather than a web page containing an image. It must also have a scheme of HTTP or HTTPS.
population.id A string that specifies the identifier of the population resource associated with the user.
preferredLanguage A string that specifies the user’s preferred written or spoken languages, which are optional. This may be explicitly set to null when updating a user to unset it. If provided, the format of the value is the same as the HTTP Accept-Language header field (not including Accept-Language:) and is specified in Section 5.3.5 of RFC 7231. For example: en-US, en-gb;q=0.8, en;q=0.7.
primaryPhone A string that specifies the user’s primary phone number, which is optional. This might also match the mobilePhone attribute. This may be explicitly set to null when updating a user to unset it. If provided, it must consist of a leading plus sign, 1 to 3-digit country code, dot separator, 4 to 14-digit phone number, and optional 1 to 8-digit extension (for example, +1.3034682900x1234).
timezone A string that specifies the user’s time zone, which is optional. This can be explicitly set to null when updating a user to unset it. If provided, it must conform with the IANA Time Zone database format [RFC6557], also known as the “Olson” time zone database format [Olson-TZ] for example, “America/Los_Angeles”).
title A string that specifies the user’s title, which is optional, such as “Vice President”. This can be explicitly set to null when updating a user to unset it.
type A string that specifies the user’s type, which is optional. This can be explicitly set to null when updating a user to unset it. This attribute is organization-specific and has no special meaning within the PingOne platform. It could have values of “Contractor”, “Employee”, “Intern”, “Temp”, “External”, and “Unknown”.
updatedAt The time the resource was last updated.
username A string that specifies the user name, which must be provided and must be unique within an environment. The username must either be a well-formed email address or a string of any Unicode letter, mark (for example, accent, umlaut), dot, underscore, or hyphen. It can have a length of no more than 128 characters.

Response codes

Code Message
200 Successful operation.
201 Successfully created.
204 Successfully removed. No content.
400 The request was invalid.
401 You are not authenticated to perform this operation.
404 The specified object doesn’t exist.
409 Uniqueness constraint violation.

Endpoint examples

Get users

The following sample shows the GET /environments/{environmentId}/users operation to return a list of all user resources for the specified environment.

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

The response data looks like this:

{
  "_links" : {
    "self" : {
      "href" : "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users"
    }
  },
  "_embedded" : {
    "users" : [ {
      "_links" : {
        "self" : {
          "href" : "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0"
        },
        "password": {
            "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.validate": {
            "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"
        },
        "account.sendVerificationCode": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af"
        },
      "id" : "9a774ad6-b6b6-4179-af87-226cd68955f0",
      "environment" : {
        "id" : "02d37832-476a-431b-8a60-d77cecd7005c"
      },
      "population" : {
        "id" : "7c686ee8-a0cc-4c6f-8336-a37bb0384acd"
      },
      "username" : "Joe",
      "enabled": true,
      "lifecycle": {
          "status": "ACCOUNT_OK"
      },
      "mfaEnabled": false,
      "email" : "joe@ping.com",
      "createdAt" : "2018-05-15T19:23:25.089Z",
      "updatedAt" : "2018-05-15T19:23:25.089Z"
    },
    {
      "_links" : {
        "self" : {
          "href" : "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/3987b40b-c4f9-4c3a-9c23-8b957c8cfced"
        },
        "password": {
            "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.validate": {
            "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"
        },
        "account.sendVerificationCode": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af"
        },
      "id" : "3987b40b-c4f9-4c3a-9c23-8b957c8cfced",
      "environment" : {
        "id" : "02d37832-476a-431b-8a60-d77cecd7005c"
      },
      "population" : {
        "id" : "c47e0d4e-10c9-4589-9046-6652e014a786"
      },
      "username" : "ashley_graham",
      "enabled": true,
      "lifecycle": {
          "status": "ACCOUNT_OK"
      },
      "mfaEnabled": false,
      "name" : {
        "family" : "graham",
        "given" : "ashley"
      },
      "email" : "do-not-send@pingidentity.com",
      "createdAt" : "2018-06-01T19:44:21.780Z",
      "updatedAt" : "2018-06-01T19:44:21.780Z"
    } ]
  },
  "count" : 2,
  "size" : 2
}

Get one user

To get data for a single user resource, the GET /environments/{environmentId}/users/{userId} operation returns data only for the user resource with the ID specified in the request URL.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}" \
-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"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca"
        },
        "population": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/populations/a701eb22-849d-4168-b756-6c20fc087c2f"
        },
        "password": {
            "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.validate": {
            "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"
        },
        "account.sendVerificationCode": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af"
        }
    },
    "id": "c3042000-188f-4bc7-a269-dee1602cf7af",
    "environment": {
        "id": "5da98f13-ad62-4234-ba04-2b6e2e85c8ca"
    },
    "population": {
        "id": "a701eb22-849d-4168-b756-6c20fc087c2f"
    },
    "createdAt": "2019-01-08T20:18:31.264Z",
    "email": "joe@ping.com",
    "enabled": true,
    "lifecycle": {
        "status": "ACCOUNT_OK"
    },
    "mfaEnabled": false,
    "name": {
        "given": "Joe",
        "family": "Jones"
    },
    "nickname": "Joey",
    "updatedAt": "2019-01-08T20:59:56.871Z",
    "username": "joejones"
}

Create users

The following sample shows the POST /environments/{environmentId}/users operation to add a new user resource to the specified environment. This operation creates a new user but does not support an attribute to set the new user’s password. To create a user and set the password, see Import users.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/users" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "username": "lindajones",
  "email": "ljones@company.com",
  "population" : {
    "id" : "21731b50-6b54-41b0-8454-9cd9de62a7a1"
    }
}'

New users must be assigned to a population resource identified by its ID, and the request must set values for the username and email attributes. If successful, the response returns a 201 Successfully created message and shows the new user resource’s property data.

Note: For information about setting a user’s password after creating the new user, see Set password.

Import users

The import users operation gives privileged applications the ability to create a new user and set the user’s password. The password attribute in this operation uses the same format for specifying passwords as the set password request, allowing both cleartext and pre-encoded password values. This endpoint requires the dir:import:user permission, which is not included in the Identity Data Admin role (or any other administrator role).

The following sample shows the POST /environments/{environmentId}/users operation to import a new user resource to the specified environment. This operation uses the application/vnd.pingidentity.user.import+json custom content type in the request header.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/users" \
-H 'Content-type: application/vnd.pingidentity.user.import+json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "email":"angelamontero@pingidentity.com",
  "name":{  
     "given":"angela",
     "family":"montero"
  },
  "population":{  
     "id":"87972995-664b-11ff-99f8-qw341dac3667"
  },
  "username":"angelamontero",
  "password":{
     "value": "{SSHA512}UkGWfORubNKFpFBWh+Lgy4FrciclzUXneuryV+B+zBDR4Gqd5wvMqAvKRixgQWoZlZUgq8Wh40uMK3s6bWpzWt1/TqQH02hX",
     "forceChange": false
  }
 }'

New users must be assigned to a population resource identified by its ID, and the request must set values for the username and email attributes. In addition, this operation supports the password attribute, which can accept a pre-encoded password value and a forceChange value of false. If successful, the response returns a 201 Successfully created message and shows the new user resource’s property data.

Note: Pre-encoded passwords are specified by the name of the encoding scheme followed by an encoded representation of the password (as shown in the example above). Supported encoding schemes are bcrypt, scrypt, salted SHA1, salted SHA256, salted SHA384, and salted SHA512.

For more information about pre-encoded passwords, see Set password. For import operations, if a pre-encoded password is not accepted by PingOne, then it does not conform to the supported encoding schemes described in the Set password topic.

Update users

You can use the PUT /environments/{environmentId}/users/{userId} operation to update existing attribute properties. For PUT requests, the update operation removes any existing attribute property values omitted from the request body.

curl -X "PUT" "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
    "username": "joe@example.com",
    "name": {
        "formatted": "Joe Smith",
        "given": "Joe",
        "middle": "H.",
        "family": "Smith",
        "honorificPrefix": "Dr.",
        "honorificSuffix": "IV"
    },
    "nickname": "Putty",
    "title": "Senior Director",
    "preferredLanguage": "en-gb;q=0.8, en;q=0.7",
    "locale": "en-gb",
    "email": "joe@example.com",
    "primaryPhone": "+1.2225554444",
    "mobilePhone": "+1.4445552222",
    "photo": {
        "href": "<url-to-image>"
    },
    "address": {
        "streetAddress": "123 Main Street",
        "locality": "Springfield",
        "region": "WA",
        "postalCode": "98701",
        "countryCode": "US"
    },
    "accountId": "5",
    "type": "tele",
    "timezone": "America/Los_Angeles"
}'

The response data shows the updates for all attribute values specified in the request body.

Partial update

The following sample shows the PATCH /environments/{environmentId}/users/{userId} operation to update existing attribute properties. For the PATCH operation, the update operation targets only those attribute values specified in the request body. Attributes omitted from the request body are not updated or removed.

curl -X "PATCH" "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
    "username": "joesmith@example.com",
    "email": "joesmith@example.com"
}'

Get user enabled setting

When a new user resource is created, the value specified for the enabled attribute determines the user’s ability to authenticate. If the enabled attribute is omitted from the POST request, the value is set to true by default.

For existing users, you can use the GET /environments/{environmentId}/users/{userId}/enabled operation to check whether the specified user is enabled or disabled.

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

The response data for an enabled user looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0/enabled"
        },
        "user": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0"
        }
    },
    "enabled": true
}

Update user enabled setting

You can modify the user’s enabled attribute value by calling the PUT /environments/{environmentId}/users/{userId}/enabled endpoint.

The following sample shows the PUT /environments/{environmentId}/users/{userId}/enabled operation to disable the user resource’s ability to authenticate.

curl -X "PUT" "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/enabled" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "enabled": "false"
}'

The response data with the updated setting looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0/enabled"
        },
        "user": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0"
        }
    },
    "enabled": false
}

Get MFA enabled setting

When a new user resource is created, the mfaEnabled attribute that controls the user’s ability to use multi-factor authentication is set to false by default.

For existing users, you can use the GET /environments/{environmentId}/users/{userId}/mfaEnabled operation to check whether the specified user is enabled or disabled.

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

The response data looks like this:

{
  "_links": {
    "self": {
      "href": "https://api.pingone.com/v1/environments/b7372995-824b-44ff-99f8-ab151dac3263/users/05ad3cc6-8723-4f85-9711-05ad549717f6/mfaEnabled"
    },
    "user": {
      "href": "https://api.pingone.com/v1/environments/b7372995-824b-44ff-99f8-ab151dac3263/users/05ad3cc6-8723-4f85-9711-05ad549717f6"
    }
  },
  "mfaEnabled": false
}

Update MFA enabled setting

The mfaEnabled attribute is a read-only attribute that cannot be changed through calls to PUT /environments/{environmentId}/users/{userId} or PATCH /environments/{environmentId}/users/{userId}. However, you can update the mfaEnabled value by calling the PUT /environments/{environmentId}/users/{userId}/mfaEnabled endpoint.

The following sample shows the PUT /environments/{environmentId}/users/{userId}/mfaEnabled operation to enable the user resource’s ability to use multi-factor authentication.

curl -X "PUT" "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/mfaEnabled" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
   "mfaEnabled": "true"
}'

The response returns a 200 OK message. The response data looks like this:

{
  "_links": {
    "self": {
      "href": "https://api.pingone.com/v1/environments/b7372995-824b-44ff-99f8-ab151dac3263/users/05ad3cc6-8723-4f85-9711-05ad549717f6/mfaEnabled"
    },
    "user": {
      "href": "https://api.pingone.com/v1/environments/b7372995-824b-44ff-99f8-ab151dac3263/users/05ad3cc6-8723-4f85-9711-05ad549717f6"
    }
  },
  "mfaEnabled": true
}

Verify users

The verified property indicates whether the user has been verified through email or sms. When a user resource is created, the lifecycle.status property can be set to VERIFICATION_REQUIRED. If this property is set to VERIFICATION_REQUIRED, a verification code is sent to the email address provided in the user resource’s email property to verify the account.

The following sample shows the POST /environments/{envId}/users/{userId} operation to send a verification email with a verification code to an unverified user. This operation uses the application/vnd.pingidentity.user.verify+json custom content type in the request header.

curl -X "POST" "https://api.pingone.com/v1/environments/{envId}/users/{userId}" \
-H 'Content-type: application/vnd.pingidentity.user.verify+json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "verificationCode": <code>
}'

If the user loses or did not receive the verification code, a new verification code can be sent using the POST /environments/{envId}/users/{userId} operation. For the code resend operation, the application/vnd.pingidentity.user.sendVerificationCode+json custom content type is required in the request header.

curl -X "POST" "https://api.pingone.com/v1/environments/{envId}/users/{userId}" \
-H 'Content-type: application/vnd.pingidentity.user.sendVerificationCode+json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "verificationCode": <code>
}'

Get user population setting

To get the population ID associated with a single user resource, the GET /environments/{environmentId}/users/{userId}/population operation returns the population setting for the user resource with the ID specified in the request URL.

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

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/populations/a701eb22-849d-4168-b756-6c20fc087c2f"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca"
        }
    },
    "id": "a701eb22-849d-4168-b756-6c20fc087c2f",
    "environment": {
        "id": "5da98f13-ad62-4234-ba04-2b6e2e85c8ca"
    },
    "name": "Engineering",
    "description": "Engineering population",
    "userCount": 10,
    "createdAt": "2019-01-08T20:15:55.180Z",
    "updatedAt": "2019-01-08T20:15:55.180Z"
}

Update user population setting

To move a user from one population to another, you need to know the ID of the new population resource to associate with the user. To retrieve the list of all population IDs for a specified environment, you can call the GET /environments/{environmentId}/populations method.

The following sample shows the PUT /environments/{environmentId}/users/{userId}/population operation to associate the user with the different population.

curl -X "PUT" "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/population" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "id": "21731b50-6b54-41b0-8454-9cd9de62a7a1"
}'

In the request body, the id attribute value is the population ID for the new population to associate with the user.

Create user role assignments

The permissions service provides operations to view all roles defined in the platform and manage the roles assigned to specific users. When you assign a role to a user, you provide the attribute values required to identify the role and designate the role assignment scope for this user.

The following sample shows the POST /environments/{environmentId}/users/{userId}/roleAssignments operation to update the role assignment for the user in the specified environment resource.

curl -X POST "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/roleAssignments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken" \
-d "{
  "role": {
    "id": "1813bc13-8d13-4e88-a825-d40bfe82777b",
  },
  "scope": {
    "id": "d928aa51-c194-4333-9cf5-0fd0c9b7d62f",
    "type": "ORGANIZATION"
  }
}"

The request URL identifies the environment ID and user ID. The request body specifies the role ID and the scope attribute values. The scope attribute provides the resource ID and resource type to designate the role assignment scope associated with this actor. In this sample, the scope type is ORGANIZATION and the specific organization to which the role assignment scope applies is specified in the id value.

For more information about role assignment scopes, see Roles.

Get user role assignments

Users in PingOne can be assigned one or more roles. You can view the roles assigned to a specific user, and you can view the role assignment scopes that define the limitations of each role.

The GET /environments/{environmentId}/users/{userId}/roleAssignments operation returns the list of roles assigned to the user identified by the user’s ID.

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

The request URL identifies the environment ID and the user’s ID.

The response data for a user with more than one role looks like this. Note that the list of permissions for the roles in this sample has been edited. The data returned from this GET request will show every permission assigned to each role.

{
  "count" : 4,
  "size" : 4,
  "_links" : {
    "self" : {
      "href" : "https://api.pingone.com/environments/76777665-61cb-415a-b0f7-3c6f7a7235c3/users/986ab733-6dc8-4d3b-bc66-0cdaaed00e1f/roleAssignments"
    }
  },
  "_embedded" : {
    "roleAssignments" : [ {
      "id" : "170e554e-dd6f-427f-9115-a253e3cf3911",
      "role" : {
        "id" : "0bd9c966-7664-4ac1-b059-0ff9293908e2",
        "name" : "Identity Data Admin",
        "description" : "Identity Data Admin",
        "applicableTo" : [ "POPULATION", "ENVIRONMENT" ],
        "permissions" : [
         {
          "namespace" : "dir",
          "description" : "Read users"
         }
        ]
      },
      "actor" : {
        "id" : "986ab733-6dc8-4d3b-bc66-0cdaaed00e1f",
        "environmentId" : "76777665-61cb-415a-b0f7-3c6f7a7235c3",
        "type" : "USER"
      },
      "scope" : {
        "id" : "07267d87-8b3f-4524-8175-b5dacd221121",
        "type" : "ENVIRONMENT"
      }
    }, {
      "id" : "97898b41-914f-477e-88ae-df57f51ea57c",
      "role" : {
        "id" : "29ddce68-cd7f-4b2a-b6fc-f7a19553b496",
        "name" : "Environment Admin",
        "description" : "Environment Admin",
        "applicableTo" : [ "ORGANIZATION", "ENVIRONMENT" ],
        "permissions" : [
        {
          "namespace" : "dir",
          "description" : "Delete populations"
        }
        ]
      },
      "actor" : {
        "id" : "986ab733-6dc8-4d3b-bc66-0cdaaed00e1f",
        "environmentId" : "76777665-61cb-415a-b0f7-3c6f7a7235c3",
        "type" : "USER"
      },
      "scope" : {
        "id" : "07267d87-8b3f-4524-8175-b5dacd221121",
        "type" : "ENVIRONMENT"
      }
    }, {
      "id" : "26299e68-1c9d-40ba-801f-eb8d42d6f748",
      "role" : {
        "id" : "0bd9c966-7664-4ac1-b059-0ff9293908e2",
        "name" : "Identity Data Admin",
        "description" : "Identity Data Admin",
        "applicableTo" : [ "POPULATION", "ENVIRONMENT" ],
        "permissions" : [
        {
          "namespace" : "dir",
          "description" : "Update users"
        }
       ]
      },
      "actor" : {
        "id" : "986ab733-6dc8-4d3b-bc66-0cdaaed00e1f",
        "environmentId" : "76777665-61cb-415a-b0f7-3c6f7a7235c3",
        "type" : "USER"
      },
      "scope" : {
        "id" : "1c6a8c00-04e8-4573-9b32-64d6d107548c",
        "type" : "ENVIRONMENT"
      }
    }, {
      "id" : "61a7abee-1290-4633-ad97-e98c6366107c",
      "role" : {
        "id" : "29ddce68-cd7f-4b2a-b6fc-f7a19553b496",
        "name" : "Environment Admin",
        "description" : "Environment Admin",
        "applicableTo" : [ "ORGANIZATION", "ENVIRONMENT" ],
        "permissions" : [
        {
          "namespace" : "api_client_config",
          "description" : "Update or Reset secret for Client"
        }
       ]
      },
      "actor" : {
        "id" : "986ab733-6dc8-4d3b-bc66-0cdaaed00e1f",
        "environmentId" : "76777665-61cb-415a-b0f7-3c6f7a7235c3",
        "type" : "USER"
      },
      "scope" : {
        "id" : "1c6a8c00-04e8-4573-9b32-64d6d107548c",
        "type" : "ENVIRONMENT"
      }
    } ]
  }
}

The response data also shows that this user has two roles: Environment Admin and Identity Data Admin. In addition, each of these roles is defined by two role assignment scopes. The JSON excerpt below shows the two role assignment scopes for the Identity Data Admin role.

"_embedded" : {
  "roleAssignments" : [ {
    "id" : "170e554e-dd6f-427f-9115-a253e3cf3911",
    "role" : {
      "id" : "0bd9c966-7664-4ac1-b059-0ff9293908e2",
      "name" : "Identity Data Admin",
      "description" : "Identity Data Admin",
      "applicableTo" : [ "POPULATION", "ENVIRONMENT" ],
      "permissions" : [
       {
        "namespace" : "dir",
        "description" : "Read users"
       }
      ]
    },
    "actor" : {
      "id" : "986ab733-6dc8-4d3b-bc66-0cdaaed00e1f",
      "environmentId" : "76777665-61cb-415a-b0f7-3c6f7a7235c3",
      "type" : "USER"
    },
    "scope" : {
      "id" : "07267d87-8b3f-4524-8175-b5dacd221121",
      "type" : "ENVIRONMENT"
    }
  }, {
    "id" : "26299e68-1c9d-40ba-801f-eb8d42d6f748",
    "role" : {
      "id" : "0bd9c966-7664-4ac1-b059-0ff9293908e2",
      "name" : "Identity Data Admin",
      "description" : "Identity Data Admin",
      "applicableTo" : [ "POPULATION", "ENVIRONMENT" ],
      "permissions" : [
      {
        "namespace" : "dir",
        "description" : "Read users"
      }
     ]
    },
    "actor" : {
      "id" : "986ab733-6dc8-4d3b-bc66-0cdaaed00e1f",
      "environmentId" : "76777665-61cb-415a-b0f7-3c6f7a7235c3",
      "type" : "USER"
    },
    "scope" : {
      "id" : "1c6a8c00-04e8-4573-9b32-64d6d107548c",
      "type" : "ENVIRONMENT"
    }
   }
  } ]
}

The id attribute for each scope attribute specifies a different environment resource ID.

Get one user role assignment

The GET /environments/{environmentId}/users/{userId}/roleAssignments/{roleAssignmentId} operation returns the specific role assignment assigned to the user identified by the user’s ID.

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

Delete role assignments

The following sample shows the DELETE /environments/{environmentId}/users/{userId}/roleAssignments/{roleAssignmentId} operation to delete the role assignment specified by its ID in the request URL. The role assignment is deleted only for the actor identified in the request URL.

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

When successful, the DELETE request returns a code 204 No Content message.

Delete users

To delete a user resource from the directory, you need to specify the environment and user IDs.

The following sample shows the DELETE /environments/{environmentId}/users/{userId} operation to remove the specified user resource from the directory.

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

For successful delete operations, a 204 NO CONTENT message is returned by the request.

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

Note: For information about password and apssword policy data model properties, see Password policies data model.

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 is set and can be used to log in.

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

Note: This operation cannot be used if the user is disabled or if the password status is NO_PASSWORD or PASSWORD_LOCKED_OUT.

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}UkGWfORubNKFpFBWh+Lgy4FrciclzUXneuryV+B+zBDR4Gqd5wvMqAvKRixgQWoZlZUgq8Wh40uMK3s6bWpzWt1/TqQH02hX). 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}

Note: Pre-encoded passwords must use the LDAP userPassword syntax supported by PingDirectory and other directory servers. For more information about the LDAP userPassword attribute, see Hashed attribute values for userPassword. For import operations, if a pre-encoded password is not accepted by PingOne, then it does not conform to the supported encoding schemes described above.

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.