Password policies


Password policies

The password policies endpoints implement functions to list password policies associated with an environment, get information about a specific password policy, and modify a password policy’s attributes. To perform password policy management operations, you need to know the environment ID for the associated password policy.

Password policies API operations

The passwords endpoints support the following operations:

For hands-on experience with the Applications 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.

Password policies data model

Property Description
currentPassword A string that specifies the current password that must be verified before the new password is set. Required for self change (when the user whose password being changed is the same as the actor in the access token) when the user already has a password.
default Boolean that specifies whether this password policy is enforced within the environment. When set to true, all other password policies are set to false.
description A string that specifies the brief description of the password policy.
environment.id A string that specifies the ID of the environment resource referenced by this relationship.
excludesCommonlyUsed Boolean that ensures the password is not one of the commonly used passwords.
excludesProfileData Boolean that ensure the password does not match (exact and substring) the value of any attribute in the user’s profile, such as name, phone number, or address.
history.count An integer that specifies the number of prior passwords to keep for prevention of password re-use.
history.retentionDays An integer that specifies the length of time to keep recent passwords for prevention of password re-use.
id A string that specifies the password resource’s unique identifier.
lastChangedAt The time the password was last changed. This property is not returned if the user does not have a password.
length.max An integer that specifies the maximum number of characters allowed for the password.
length.min An integer that specifies the minimum number of characters required for the password.
lockout.durationSeconds An integer that specifies the length of time before a password is automatically moved out of the lock out state.
lockout.failureCount An integer that specifies the number of tries before a password is placed in the lock out state.
maxAgeDays An integer that specifies the maximum number of days the same password may be used before it must be changed.
maxRepeatedCharacters An integer that specifies the maximum number of repeated characters allowed. This property is not enforced when not present.
minCharacters A set of key-value pairs where the key is a string containing all the characters that may be included and the value is the minimum number of times one of the characters must appear in the password. This property is not enforced when not present.
minComplexity An integer that specifies the minimum complexity of the password based on the concept of password haystacks. Value is number of days required toexhaust the entire search space during a brute force attack. This property is not enforced when not present.
minUniqueCharacters An integer that specifies the minimum number of unique characters required. This property is not enforced when not present.
name A string that specifies the name of the password policy.
newPassword A string that specifies the new password.
notSimilarToCurrent Boolean that ensures that the proposed password is not too similar to the user’s current password based on the Levenshtein distance algorithm.
passwordPolicy.id A string that specifies the ID of the password policy resource referenced by this relationship.
secondsUntilUnlock An integer that specifies the number of seconds before the password may be used again after a lock out. If absent, the password must be reset by an administrator before it may be used again after a lockout.
status A string that specifies the current status of the password. Options are OK, NO_PASSWORD, PASSWORD_EXPIRED, PASSWORD_LOCKED_OUT, and MUST_CHANGE_PASSWORD.
user.id A string that specifies the ID of the user resource referenced by this relationship.
warnings.expires The password will expire on the specified date and time.
warnings.failuresRemaining There has been recent attempts to check the password unsuccessfully and will be locked out after the indicated number of further unsuccessful attempts.
warnings.noChangeUntil The password was recently self-changed and cannot be self-changed again until the specified date and time.

Response codes

Code Message
200 Successful operation.
400 Bad Request (e.g., invalid username or password)
401 Unauthorized (e.g., invalid token or missing permissions)
404 Not Found (e.g., user or environment)

Note: The Environment Admin role is required to perform password policy management operations.

Endpoint examples

Get password policies

You can get all password policies for an environment or a specific password policy.

The GET /environments/{environmentId}/passwordPolicies operation returns all password policies for the selected environment.

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

In this sample, the environment has two defined password policies, a Standard policy and a Passphrase policy. The response data looks like this:

{
  "_links" : {
    "self" : {
      "href" : "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/passwordPolicies"
    }
  },
  "_embedded" : {
    "passwordPolicies" : [ {
      "_links" : {
        "self" : {
          "href" : "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/passwordPolicies/0bda42bc-d54f-449f-86d3-01018f6ef0ad"
        },
        "environment" : {
          "href" : "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba"
        }
      },
      "id" : "0bda42bc-d54f-449f-86d3-01018f6ef0ad",
      "environment" : {
        "id" : "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
      },
      "name" : "Standard",
      "description" : "A standard policy that incorporates industry best practices",
      "excludesProfileData" : true,
      "notSimilarToCurrent" : true,
      "excludesCommonlyUsed" : true,
      "maxAgeDays" : 90,
      "maxRepeatedCharacters" : 2,
      "minUniqueCharacters" : 5,
      "history" : {
        "count" : 6,
        "retentionDays" : 365
      },
      "lockout" : {
        "failureCount" : 5,
        "durationSeconds" : 900
      },
      "length" : {
        "min" : 8,
        "max" : 255
      },
      "minCharacters" : {
        "abcdefghijklmnopqrstuvwxyz" : 1,
        "ABCDEFGHIJKLMNOPQRSTUVWXYZ" : 1,
        "123456890" : 1,
        "~!@#$%^&*()-_=+[]{}|;:,.<>/?" : 1
      },
      "default" : true
    }, {
      "_links" : {
        "self" : {
          "href" : "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/passwordPolicies/0bda42bc-d54f-449f-b22d-3c605c617410"
        },
        "environment" : {
          "href" : "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba"
        }
      },
      "id" : "0bda42bc-d54f-449f-b22d-3c605c617410",
      "environment" : {
        "id" : "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
      },
      "name" : "Passphrase",
      "description" : "A policy that encourage the use of passphrases",
      "excludesProfileData" : true,
      "notSimilarToCurrent" : true,
      "excludesCommonlyUsed" : true,
      "minComplexity" : 7,
      "maxAgeDays" : 90,
      "history" : {
        "count" : 6,
        "retentionDays" : 365
      },
      "lockout" : {
        "failureCount" : 5,
        "durationSeconds" : 900
      },
      "default" : false
    } ]
  },
  "count" : 2,
  "size" : 2
}

Get one password policy

The GET /environments/{environmentId}/passwordPolicies/{policyId} operation returns information for a single password policy specified by the policyId attribute in the request URL.

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

The response data shows information for the password policy identified by its id.

Update a password policy

You can update a specified password policy by changing the value of its default property. The PUT /environments/{environmentId}/passwordPolicies/{policyId} operation updates the password policy specified by the policy ID in the request URL.

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