PingOne Platform APIs

Password Check

   

POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/password

The sample shows the POST {{apiPath}}/environments/{{envID}}/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.

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.

Users who authenticate with an authoritative identity provider cannot perform any self-service actions on passwords. Their user.identityProvider.id attribute is not null and their user.identityProvider.type attribute is not PING_ONE.

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.

Prerequisites

Request Model
Property Type Required?

password

String

Required

Refer to the User passwords data model for full property descriptions.

Headers

Authorization      Bearer {{accessToken}}

Content-Type      application/vnd.pingidentity.password.check+json

Body

raw ( application/vnd.pingidentity.password.check+json )

{
  "password":"{{password}}"
}

Example Request

  • cURL

  • C#

  • Go

  • HTTP

  • Java

  • jQuery

  • NodeJS

  • Python

  • PHP

  • Ruby

  • Swift

curl --location --globoff '{{apiPath}}/environments/{{envID}}/users/{{userID}}/password' \
--header 'Content-Type: application/vnd.pingidentity.password.check+json' \
--header 'Authorization: Bearer {{accessToken}}' \
--data '{
  "password":"{{password}}"
}'
var options = new RestClientOptions("{{apiPath}}/environments/{{envID}}/users/{{userID}}/password")
{
  MaxTimeout = -1,
};
var client = new RestClient(options);
var request = new RestRequest("", Method.Post);
request.AddHeader("Content-Type", "application/vnd.pingidentity.password.check+json");
request.AddHeader("Authorization", "Bearer {{accessToken}}");
var body = @"{" + "\n" +
@"  ""password"":""{{password}}""" + "\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 := "POST"

  payload := strings.NewReader(`{
  "password":"{{password}}"
}`)

  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.check+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))
}
POST /environments/{{envID}}/users/{{userID}}/password HTTP/1.1
Host: {{apiPath}}
Content-Type: application/vnd.pingidentity.password.check+json
Authorization: Bearer {{accessToken}}

{
  "password":"{{password}}"
}
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/vnd.pingidentity.password.check+json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"password\":\"{{password}}\"\n}");
Request request = new Request.Builder()
  .url("{{apiPath}}/environments/{{envID}}/users/{{userID}}/password")
  .method("POST", body)
  .addHeader("Content-Type", "application/vnd.pingidentity.password.check+json")
  .addHeader("Authorization", "Bearer {{accessToken}}")
  .build();
Response response = client.newCall(request).execute();
var settings = {
  "url": "{{apiPath}}/environments/{{envID}}/users/{{userID}}/password",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/vnd.pingidentity.password.check+json",
    "Authorization": "Bearer {{accessToken}}"
  },
  "data": JSON.stringify({
    "password": "{{password}}"
  }),
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
var request = require('request');
var options = {
  'method': 'POST',
  'url': '{{apiPath}}/environments/{{envID}}/users/{{userID}}/password',
  'headers': {
    'Content-Type': 'application/vnd.pingidentity.password.check+json',
    'Authorization': 'Bearer {{accessToken}}'
  },
  body: JSON.stringify({
    "password": "{{password}}"
  })

};
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({
  "password": "{{password}}"
})
headers = {
  'Content-Type': 'application/vnd.pingidentity.password.check+json',
  'Authorization': 'Bearer {{accessToken}}'
}

response = requests.request("POST", 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_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Content-Type' => 'application/vnd.pingidentity.password.check+json',
  'Authorization' => 'Bearer {{accessToken}}'
));
$request->setBody('{\n  "password":"{{password}}"\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::Post.new(url)
request["Content-Type"] = "application/vnd.pingidentity.password.check+json"
request["Authorization"] = "Bearer {{accessToken}}"
request.body = JSON.dump({
  "password": "{{password}}"
})

response = http.request(request)
puts response.read_body
let parameters = "{\n  \"password\":\"{{password}}\"\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.check+json", forHTTPHeaderField: "Content-Type")
request.addValue("Bearer {{accessToken}}", forHTTPHeaderField: "Authorization")

request.httpMethod = "POST"
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()