PingOne Platform APIs

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

Request Model
Property Type Required?

value

String

Required

forceChange

Boolean

Required

password.external.gateway.id

String

Optional

password.external.gateway.correlationAttributes

Object

Optional

password.external.gateway.correlationAttributes.uid

String

Optional

password.external.gateway.correlationAttributes.mail

String

Optional

password.external.gateway.userType.id

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"
}