Update Password (Set)
PUT {{apiPath}}/environments/{{envID}}/users/{{userID}}/password
The PUT {{apiPath}}/environments/{{envID}}/users/{{userID}}/password endpoint sets a password for the user identified by the user ID and environment ID. This is most often used when the password is being imported from an external identity provider, and you want to retain the password in PingOne.
This operation uses the application/vnd.pingidentity.password.set+json custom media type as the content type in the request header.
Prerequisites
-
Refer to User Operations and User Passwords for important overview information.
Request Model
| Property | Type | Required? |
|---|---|---|
|
String |
Required |
|
Boolean |
Required |
|
String |
Optional |
|
Object |
Optional |
|
String |
Optional |
|
String |
Optional |
|
String |
Optional |
Refer to the User operations data model for full property descriptions.
The request body shows how to specify the optional password.external.gateway object to reference an external gateway for the set password operation, if the user information is stored in an external directory. Refer to the Users data model for descriptions of the password.external.gateway properties.
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 bypassPolicy value specifies whether the user’s password policy should be ignored. If this property is omitted from the request, its value is set to false.
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. Refer to Password encoding for our supported encodings for passwords.
Password import errors
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.
Headers
Authorization Bearer {{accessToken}}
Content-Type application/vnd.pingidentity.password.set+json
Body
raw ( application/vnd.pingidentity.password.set+json )
{
"value": "{SSHA512}UkGWfORubNKFpFBWh+Lgy4FrciclzUXneuryV+B+zBDR4Gqd5wvMqAvKRixgQWoZlZUgq8Wh40uMK3s6bWpzWt1/TqQH02hX",
"forceChange": true,
"external": {
"gateway": {
"id": "{{gatewayID}}",
"correlationAttributes": {
"uid": "eFudd",
"mail": "eFudd@example.com"
},
"userType": {
"id": "{{userTypeID}}"
}
}
}
}
Example Request
-
cURL
-
C#
-
Go
-
HTTP
-
Java
-
jQuery
-
NodeJS
-
Python
-
PHP
-
Ruby
-
Swift
curl --location --globoff --request PUT '{{apiPath}}/environments/{{envID}}/users/{{userID}}/password' \
--header 'Content-Type: application/vnd.pingidentity.password.set+json' \
--header 'Authorization: Bearer {{accessToken}}' \
--data-raw '{
"value": "{SSHA512}UkGWfORubNKFpFBWh+Lgy4FrciclzUXneuryV+B+zBDR4Gqd5wvMqAvKRixgQWoZlZUgq8Wh40uMK3s6bWpzWt1/TqQH02hX",
"forceChange": true,
"external": {
"gateway": {
"id": "{{gatewayID}}",
"correlationAttributes": {
"uid": "eFudd",
"mail": "eFudd@example.com"
},
"userType": {
"id": "{{userTypeID}}"
}
}
}
}'
var options = new RestClientOptions("{{apiPath}}/environments/{{envID}}/users/{{userID}}/password")
{
MaxTimeout = -1,
};
var client = new RestClient(options);
var request = new RestRequest("", Method.Put);
request.AddHeader("Content-Type", "application/vnd.pingidentity.password.set+json");
request.AddHeader("Authorization", "Bearer {{accessToken}}");
var body = @"{" + "\n" +
@" ""value"": ""{SSHA512}UkGWfORubNKFpFBWh+Lgy4FrciclzUXneuryV+B+zBDR4Gqd5wvMqAvKRixgQWoZlZUgq8Wh40uMK3s6bWpzWt1/TqQH02hX""," + "\n" +
@" ""forceChange"": true," + "\n" +
@" ""external"": {" + "\n" +
@" ""gateway"": {" + "\n" +
@" ""id"": ""{{gatewayID}}""," + "\n" +
@" ""correlationAttributes"": {" + "\n" +
@" ""uid"": ""eFudd""," + "\n" +
@" ""mail"": ""eFudd@example.com""" + "\n" +
@" }," + "\n" +
@" ""userType"": {" + "\n" +
@" ""id"": ""{{userTypeID}}""" + "\n" +
@" }" + "\n" +
@" }" + "\n" +
@" }" + "\n" +
@"}";
request.AddStringBody(body, DataFormat.Json);
RestResponse response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "{{apiPath}}/environments/{{envID}}/users/{{userID}}/password"
method := "PUT"
payload := strings.NewReader(`{
"value": "{SSHA512}UkGWfORubNKFpFBWh+Lgy4FrciclzUXneuryV+B+zBDR4Gqd5wvMqAvKRixgQWoZlZUgq8Wh40uMK3s6bWpzWt1/TqQH02hX",
"forceChange": true,
"external": {
"gateway": {
"id": "{{gatewayID}}",
"correlationAttributes": {
"uid": "eFudd",
"mail": "eFudd@example.com"
},
"userType": {
"id": "{{userTypeID}}"
}
}
}
}`)
client := &http.Client {
}
req, err := http.NewRequest(method, url, payload)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Content-Type", "application/vnd.pingidentity.password.set+json")
req.Header.Add("Authorization", "Bearer {{accessToken}}")
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
PUT /environments/{{envID}}/users/{{userID}}/password HTTP/1.1
Host: {{apiPath}}
Content-Type: application/vnd.pingidentity.password.set+json
Authorization: Bearer {{accessToken}}
{
"value": "{SSHA512}UkGWfORubNKFpFBWh+Lgy4FrciclzUXneuryV+B+zBDR4Gqd5wvMqAvKRixgQWoZlZUgq8Wh40uMK3s6bWpzWt1/TqQH02hX",
"forceChange": true,
"external": {
"gateway": {
"id": "{{gatewayID}}",
"correlationAttributes": {
"uid": "eFudd",
"mail": "eFudd@example.com"
},
"userType": {
"id": "{{userTypeID}}"
}
}
}
}
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/vnd.pingidentity.password.set+json");
RequestBody body = RequestBody.create(mediaType, "{\n \"value\": \"{SSHA512}UkGWfORubNKFpFBWh+Lgy4FrciclzUXneuryV+B+zBDR4Gqd5wvMqAvKRixgQWoZlZUgq8Wh40uMK3s6bWpzWt1/TqQH02hX\",\n \"forceChange\": true,\n \"external\": {\n \"gateway\": {\n \"id\": \"{{gatewayID}}\",\n \"correlationAttributes\": {\n \"uid\": \"eFudd\",\n \"mail\": \"eFudd@example.com\"\n },\n \"userType\": {\n \"id\": \"{{userTypeID}}\"\n }\n }\n }\n}");
Request request = new Request.Builder()
.url("{{apiPath}}/environments/{{envID}}/users/{{userID}}/password")
.method("PUT", body)
.addHeader("Content-Type", "application/vnd.pingidentity.password.set+json")
.addHeader("Authorization", "Bearer {{accessToken}}")
.build();
Response response = client.newCall(request).execute();
var settings = {
"url": "{{apiPath}}/environments/{{envID}}/users/{{userID}}/password",
"method": "PUT",
"timeout": 0,
"headers": {
"Content-Type": "application/vnd.pingidentity.password.set+json",
"Authorization": "Bearer {{accessToken}}"
},
"data": JSON.stringify({
"value": "{SSHA512}UkGWfORubNKFpFBWh+Lgy4FrciclzUXneuryV+B+zBDR4Gqd5wvMqAvKRixgQWoZlZUgq8Wh40uMK3s6bWpzWt1/TqQH02hX",
"forceChange": true,
"external": {
"gateway": {
"id": "{{gatewayID}}",
"correlationAttributes": {
"uid": "eFudd",
"mail": "eFudd@example.com"
},
"userType": {
"id": "{{userTypeID}}"
}
}
}
}),
};
$.ajax(settings).done(function (response) {
console.log(response);
});
var request = require('request');
var options = {
'method': 'PUT',
'url': '{{apiPath}}/environments/{{envID}}/users/{{userID}}/password',
'headers': {
'Content-Type': 'application/vnd.pingidentity.password.set+json',
'Authorization': 'Bearer {{accessToken}}'
},
body: JSON.stringify({
"value": "{SSHA512}UkGWfORubNKFpFBWh+Lgy4FrciclzUXneuryV+B+zBDR4Gqd5wvMqAvKRixgQWoZlZUgq8Wh40uMK3s6bWpzWt1/TqQH02hX",
"forceChange": true,
"external": {
"gateway": {
"id": "{{gatewayID}}",
"correlationAttributes": {
"uid": "eFudd",
"mail": "eFudd@example.com"
},
"userType": {
"id": "{{userTypeID}}"
}
}
}
})
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
import requests
import json
url = "{{apiPath}}/environments/{{envID}}/users/{{userID}}/password"
payload = json.dumps({
"value": "{SSHA512}UkGWfORubNKFpFBWh+Lgy4FrciclzUXneuryV+B+zBDR4Gqd5wvMqAvKRixgQWoZlZUgq8Wh40uMK3s6bWpzWt1/TqQH02hX",
"forceChange": True,
"external": {
"gateway": {
"id": "{{gatewayID}}",
"correlationAttributes": {
"uid": "eFudd",
"mail": "eFudd@example.com"
},
"userType": {
"id": "{{userTypeID}}"
}
}
}
})
headers = {
'Content-Type': 'application/vnd.pingidentity.password.set+json',
'Authorization': 'Bearer {{accessToken}}'
}
response = requests.request("PUT", url, headers=headers, data=payload)
print(response.text)
<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('{{apiPath}}/environments/{{envID}}/users/{{userID}}/password');
$request->setMethod(HTTP_Request2::METHOD_PUT);
$request->setConfig(array(
'follow_redirects' => TRUE
));
$request->setHeader(array(
'Content-Type' => 'application/vnd.pingidentity.password.set+json',
'Authorization' => 'Bearer {{accessToken}}'
));
$request->setBody('{\n "value": "{SSHA512}UkGWfORubNKFpFBWh+Lgy4FrciclzUXneuryV+B+zBDR4Gqd5wvMqAvKRixgQWoZlZUgq8Wh40uMK3s6bWpzWt1/TqQH02hX",\n "forceChange": true,\n "external": {\n "gateway": {\n "id": "{{gatewayID}}",\n "correlationAttributes": {\n "uid": "eFudd",\n "mail": "eFudd@example.com"\n },\n "userType": {\n "id": "{{userTypeID}}"\n }\n }\n }\n}');
try {
$response = $request->send();
if ($response->getStatus() == 200) {
echo $response->getBody();
}
else {
echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
$response->getReasonPhrase();
}
}
catch(HTTP_Request2_Exception $e) {
echo 'Error: ' . $e->getMessage();
}
require "uri"
require "json"
require "net/http"
url = URI("{{apiPath}}/environments/{{envID}}/users/{{userID}}/password")
http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Put.new(url)
request["Content-Type"] = "application/vnd.pingidentity.password.set+json"
request["Authorization"] = "Bearer {{accessToken}}"
request.body = JSON.dump({
"value": "{SSHA512}UkGWfORubNKFpFBWh+Lgy4FrciclzUXneuryV+B+zBDR4Gqd5wvMqAvKRixgQWoZlZUgq8Wh40uMK3s6bWpzWt1/TqQH02hX",
"forceChange": true,
"external": {
"gateway": {
"id": "{{gatewayID}}",
"correlationAttributes": {
"uid": "eFudd",
"mail": "eFudd@example.com"
},
"userType": {
"id": "{{userTypeID}}"
}
}
}
})
response = http.request(request)
puts response.read_body
let parameters = "{\n \"value\": \"{SSHA512}UkGWfORubNKFpFBWh+Lgy4FrciclzUXneuryV+B+zBDR4Gqd5wvMqAvKRixgQWoZlZUgq8Wh40uMK3s6bWpzWt1/TqQH02hX\",\n \"forceChange\": true,\n \"external\": {\n \"gateway\": {\n \"id\": \"{{gatewayID}}\",\n \"correlationAttributes\": {\n \"uid\": \"eFudd\",\n \"mail\": \"eFudd@example.com\"\n },\n \"userType\": {\n \"id\": \"{{userTypeID}}\"\n }\n }\n }\n}"
let postData = parameters.data(using: .utf8)
var request = URLRequest(url: URL(string: "{{apiPath}}/environments/{{envID}}/users/{{userID}}/password")!,timeoutInterval: Double.infinity)
request.addValue("application/vnd.pingidentity.password.set+json", forHTTPHeaderField: "Content-Type")
request.addValue("Bearer {{accessToken}}", forHTTPHeaderField: "Authorization")
request.httpMethod = "PUT"
request.httpBody = postData
let task = URLSession.shared.dataTask(with: request) { data, response, error in
guard let data = data else {
print(String(describing: error))
return
}
print(String(data: data, encoding: .utf8)!)
}
task.resume()
Example Response
200 OK
{
"_links": {
"self": {
"href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/password"
},
"environment": {
"href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"
},
"user": {
"href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/8376797d-641c-4e7b-8bc1-2fdf71916cab"
},
"passwordPolicy": {
"href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/passwordPolicies/ad53ea0b-28b3-413f-a762-46eaf929ab78"
},
"password.check": {
"href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/password"
},
"password.reset": {
"href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/password"
},
"password.set": {
"href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/password"
},
"password.recover": {
"href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/password"
}
},
"environment": {
"id": "abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"
},
"user": {
"id": "8376797d-641c-4e7b-8bc1-2fdf71916cab"
},
"passwordPolicy": {
"id": "ad53ea0b-28b3-413f-a762-46eaf929ab78"
},
"status": "MUST_CHANGE_PASSWORD",
"lastChangedAt": "2021-08-19T12:46:11.296Z"
}