Risk policies enable you to customize the risk evaluations to your specific needs. Risk policies are containers for specific risk logic. You can define multiple risk policies and deploy them to initiate different authentication flow actions based on the calculated risk. By default, every PingOne environment has an associated system-level default risk policy set.

For more information about the default risk policies, refer to the example response in Read Risk Policy Sets. Each risk policy set contains a list of risk policies. The maximum number of policy sets per environment is 100; the maximum number of policies per policy set is 100.

Risk policies have the components:

• Condition

  A Boolean predicate that defines when the policy element is evaluated to true and when it is evaluated to false.

• Result

  Defines the final result of the risk evaluation when the condition is evaluated to true.

Value comparison conditions

Value comparison conditions compare a placeholder to a value. For example:

{
  "value": "${some.placeholder}",
  "equals": "some value"
}

The value is the outcome of one of the risk predictors.

IP range conditions

IP range conditions designate IP addresses for whitelisting and blacklisting.

{
  "ipRange": ["1.1.1.1/16", "2.2.2.2/24"],
  "contains": "${transaction.ip}"
}

Override policies

Override policies are the ones with the highest priority. They should be listed at the beginning of the riskPolicies array. They can have value comparison condition rules or IP range condition rules. The risk policy array can have no override policies or multiple override policies.

Combining predictors

There are two methods of combining the predictors - Weights and Scores. When you use the Weights approach, you are determining relative weights that should be used when calculating the individual risk score for each predictor. When you use the Scores approach, you can exercise more control over the overall calculation because you can specify an exact numerical score that should be assigned when PingOne Protect determines that there is a medium or high risk level for a predictor.

Weighted policies

Weighted policies allow you to combine results from multiple predictors.

Weighted policies determine risk based on aggregated weighted risk score. These policies must be listed in the riskPolicies array after all override policies are specified. An aggregated risk score involves two weighted policies, and these policies must be the last policies in the riskPolicies array.

The weighted policies that determine the aggregated risk score complement each other and are subject to these restrictions:

• The first weighted policy should have result.level=MEDIUM and the second should have result.level=HIGH.

• The value for the condition.aggregatedWeights attribute for both policies must be the same.

• The value for the condition.between.maxScore attribute for the HIGH weighted policy must be 100.

• The value of the condition.between attribute for the two policies must be complementary. For example, if the HIGH policy has condition.between.minScore = 70, the MEDIUM policy should have condition.between.maxScore = 70.

• condition.type should be set to AGGREGATED_WEIGHTS.

• Choose the weight value assigned to each predictor outcome according to its significance. The following example shows the weight for two predictors: ipAddressReputation at 9 and the weight for geoVelocity at 4. The maximum and minimum scores are set at 60 and 90, respectively:

{
  "aggregatedWeights": [
    {
      "value": "${details.aggregatedWeights.ipAddressReputation}",
      "weight": 9
    },
    {
      "value": "${details.aggregatedWeights.geoVelocity}",
      "weight": 4
    }
  ],
  "between": {
    "minScore": 60,
    "maxScore": 90
  }
}

The value of value consists of the identifier for a specific predictor, and it takes the form ${details.aggregatedWeights.geoVelocity}, where the string after aggregatedWeights is the compact name of the relevant predictor.

Score policies

The JSON content below shows an example of a policy set that uses the Scores approach to risk calculation.

Details to note about the use of score policies:

• If you are including overrides in the policy set, they must precede the score policies.

• The policy set must include two score policies - one that includes the score range that should be translated into MEDIUM risk, and one that includes the score range that should be translated into HIGH risk.

• In terms of order, the MEDIUM policy must precede the HIGH policy.

• Use condition.between.minScore and condition.between.maxScore to define the ranges for MEDIUM risk and HIGH risk. The maxScore for MEDIUM risk should always equal the minScore for HIGH risk.

• condition.type should be set to AGGREGATED_SCORES.

• The condition object should contain an aggregatedScores object that consists of an array of value/score pairs. The value of value consists of the identifier for a specific predictor, and it takes the form ${details.userLocationAnomaly.level}, where the string between details and level is the compact name of the relevant predictor. The value of score is the score you want to assign to that predictor when it is determined that there is a high risk for the predictor. If it is determined that there is medium risk, the predictor will automatically be assigned a score equal to half of the value you specified for high risk.

• The array in condition.aggregatedScores must be identical in the MEDIUM policy that you define and the HIGH policy that you define.

{
    "id": "944fa7b4-e280-4932-80e7-01853ac9ce6d",
    "name": "aa",
    "default": false,
    "defaultResult": {
        "level": "Low"
    },
    "riskPolicies": [
        {
            "name": "ANONYMOUS_NETWORK_DETECTION",
            "result": {
                "level": "HIGH"
            },
            "condition": {
                "value": "${details.anonymousNetworkDetected}",
                "equals": true
            }
        },
        {
            "name": "GEOVELOCITY_ANOMALY",
            "result": {
                "level": "MEDIUM"
            },
            "condition": {
                "value": "${details.impossibleTravel}",
                "equals": true
            }
        },
        {
            "name": "Medium score policy",
            "result": {
                "level": "MEDIUM"
            },
            "condition": {
                "type" : "AGGREGATED_SCORES",
                "aggregatedScores": [
                    {
                        "value": "${details.userLocationAnomaly.level}",
                        "score": 40
                    },
                    {
                        "value": "${details.anonymousNetwork.level}",
                        "score": 60
                    },
                    {
                        "value": "${details.ipRisk.level}",
                        "score": 40
                    }
                ],
                "between": {
                    "minScore": 700,
                    "maxScore": 900
                }
            }
        },
        {
            "name": "High score policy",
            "result": {
                "level": "HIGH"
            },
            "condition": {
                "type" : "AGGREGATED_SCORES",
                "aggregatedScores": [
                    {
                        "value": "${details.userLocationAnomaly.level}",
                        "score": 40
                    },
                    {
                        "value": "${details.anonymousNetwork.level}",
                        "score": 60
                    },
                    {
                        "value": "${details.ipRisk.level}",
                        "score": 40
                    }
                ],
                "between": {
                    "minScore": 900,
                    "maxScore": 1000
                }
            }
        }
    ]
}

Condition type

The condition.type field indicates the type of policy you are defining. It can take any of the following values:

• AGGREGATED_SCORES
• AGGREGATED_WEIGHTS (deprecated)
• VALUE_COMPARISON
• IP_RANGE (for override policies or custom predictors)

Risk staging policy set

Risk staging policy allows you to test a policy set in parallel with another policy set. You link an existing policy set to the test policy set with a triggers object in the existing policy set, which points to the test policy set in its triggers.policySet object. Every time the existing policy set runs, it triggers the test policy set to also run. While in staging, the test policy set runs but only records its evaluation. A trigger expires 3 months from when it is set. Use Update Risk Policy Set to add the triggers object to an existing policy set.

Targeted risk policies

For standard risk policies, you must choose the risk policy to pass to the risk evaluation. Targeted risk policies allow you to define risk policies for different "targets" - combinations of transaction types, user groups, and applications that are being accessed. You can then order the targeted risk policies that you defined. When a risk evaluation is carried out, these targeted policies are processed in the order that you specified. The risk policy that is ultimately used for the risk evaluation will be the first one whose conditions (transaction type, user group, application) are met.

The following JSON snippet shows how to specify the target for a risk policy. For details, refer to the targets object in the Risk policies data model and the Create Risk Policy Set - Targeted Policy with Mitigations example.

    "targets":{
        "condition": { "and": [{
            "list": ["AUTHENTICATION", "AUTHORIZATION"],
            "contains": "${event.flow.type}"
          },
          { 
            "list": ["Sales"],
            "contains": "${event.user.groups}"
          },
          { 
            "list": ["6b6f867b-d768-4c2c-a9b6-6816da00d824", "845c9918-94d7-430c-b3d8-eafafc215fd9"],
            "contains": "${event.targetResource.id}"
          }]
        }
    }

Using mitigations in your policies

You can choose to include mitigations in your risk policies. In this context, a mitigation is an action that you recommend if a given condition is met, for example, deny access if the email reputation predictor indicates high risk. In situations where the condition is met, the action that you recommended be taken is returned in the risk evaluation response as the value of the result.mitigations[].action field.

The following JSON snippet shows how to define mitigations in a risk policy (within the riskPolicies array). For details, refer to the result.mitigations array in the Risk policies data model and the Create Risk Policy Set - Targeted Policy with Mitigations example.

    {
        "name" : "USER_LOCATION_ANOMALY",
        "result" : {
          "mitigations" : [ {
            "action" : "CUSTOM",
            "customAction" : "CustomActionForUserLocationAnomaly"
          }],
          "type" : "MITIGATION"
        },
        "condition" : {
          "value" : "${details.userLocationAnomaly.level}",
          "equals" : "High",
          "type" : "VALUE_COMPARISON"
        }
      },
      {
        "name" : "VELOCITY",
        "result" : {
          "mitigations" : [ {
            "action" : "DENY_AND_SUSPEND"
          } ],
          "type" : "MITIGATION"
        },
        "condition" : {
          "value" : "${details.ipVelocityByUser.level}",
          "equals" : "High",
          "type" : "VALUE_COMPARISON"
        }
      },{
        "name" : "USER_RISK_BEHAVIOR",
        "result" : {
          "mitigations" : [ {
            "action" : "VERIFY"
          } ],
          "type" : "MITIGATION"
        },
        "condition" : {
          "value" : "${details.userBasedRiskBehavior.level}",
          "equals" : "Medium",
          "type" : "VALUE_COMPARISON"
        }
      },
      {
        "name" : "EMAIL_REPUTATION",
        "result" : {
          "mitigations" : [ {
            "action" : "MFA",
            "mfaAuthenticationPolicyId" : "{{deviceAuthenticationPolicyID}}"
          } ],
          "type" : "MITIGATION"
        },
        "condition" : {
          "value" : "${details.emailReputation.level}",
          "equals" : "High",
          "type" : "VALUE_COMPARISON"
        }
      },
      {
        "name" : "IP_REPUTATION",
        "result" : {
          "mitigations" : [ {
            "action" : "APPROVE"
          } ],
          "type" : "MITIGATION"
        },
        "condition" : {
          "value" : "${details.ipRisk.level}",
          "equals" : "Low",
          "type" : "VALUE_COMPARISON"
        }
    }

Base risk policy set data model

Risk policies data model

This table lists the fields and objects that can be included in each of the elements in the riskPolicies array.

Risk policies events generated

Refer to Audit Reporting Events for the events generated.

Related topics

When you define authentication or other flows for your users, you can include risk evaluations at relevant points in the flow. The risk evaluation that is carried out is based on the risk policy that you specify for the evaluation. The following diagram shows a simplified sample flow that includes risk evaluation.

Note that the flow includes two distinct steps relating to risk evaluation.

The actual risk evaluation step should be added at a point in the flow where you would like to base the next action on the risk level calculated, for example, show an MFA prompt for medium or high-risk, but automatically grant access if the risk is deemed to be low.

After completion of the authentication steps, your flow should include a step to update the risk evaluation system with the results of the flow - was authentication completed successfully.

To ensure protection against fraudulent access attempts, it is essential that your flows include the SUCCESS/FAILED update step to indicate whether the flow was completed successfully or not. Many of the predictors used in risk policies are based on gradual learning of the characteristics of the access attempts made by your users, for example, where were they physically located and what operating system were they using. This learning process can only take place if your flows provide a clear indication which access attempts were made by legitimate users.

Risk evaluation data model

Event data model

A POST request uses these properties to specify information about events processed for risk evaluation.

Details data model

A POST request returns the following attributes in the details property for the specified event.

Update Risk Evaluation data model

Risk evaluations events generated

Refer to Audit Reporting Events for the events generated.

Response codes

Providing feedback for risk evaluations

Use the riskFeedback endpoint to provide feedback on the accuracy of specific risk evaluations that were carried out. The request for providing feedback takes a list of feedback items, each consisting of the risk evaluation ID, a feedback category, and a reason for including it in that category (optional). In each such request, you can include feedback for up to 100 risk evaluations.

Risk evaluation feedback data model

Below is the sample body for a request that provides feedback on three risk evaluations. Full sample request can be found here.

{
  "evaluationFeedbackItems":[
    {
      "riskEvaluation": { 
            "id": "15f1d245-33b3-4dba-849d-4df4b64b2d42"
       },
      "feedbackCategory": "FRIENDLY_BOT",
      "reason": "INTERNAL_AUTOMATION"
    },
    {
      "riskEvaluation": { 
            "id": "d1b638b4-638e-4c56-8fc6-872691c1bab1"
       },
      "feedbackCategory": "FALSE_HIGH_RISK",
      "reason": "COMPANY_VPN"
    },
    {
      "riskEvaluation": { 
            "id": "35f1d245-33b3-4dba-849d-4df4b64b2d45"
       },
      "feedbackCategory": "FALSE_HIGH_RISK"
    }  
   ]
}

Related topics

PingOne supports multiple risk predictors, which are intended to identify possible fraudulent user behaviors based on these criteria:

• Anonymous network detection

  Malicious actors typically use anonymous networks, such as unknown VPNs, Tor, and proxies to mask their IP address. PingOne Protect analyzes IP address data from a user's device to determine if the address is originating from any type of anonymous network. If so, the user can be prompted for step-up authentication or denied access. PingOne Protect also supports creating a whitelist of networks, ensuring that legitimate VPN users can access authorized resources.

• IP velocity

  IP Velocity tracks the number of distinct IPs used per user. The threshold of the number of IPs per user is based on a statistical learning of the organization's past behavior. The risk predictor learns the mean average number of distinct IPs per user per unit of time (hour), and the standard deviation. The Risk Predictor then calculates the low, medium, and high thresholds of the number of IPs per user for the organization.

• IP reputation

  IP addresses that have been involved in malicious activities, such as distributed denial-of-service (DDoS) attacks or spam activity, are considered risky. The more frequently they are used for malicious activities, the higher their risk score. If a user attempts to access an application that is associated with an IP address previously involved with suspicious activity, the probability of potentially risky behavior increases. PingOne Protect analyzes data from different intelligence sources to determine the probability an IP address is associated with malicious activity and to request stronger authentication to verify the user's identity. It also supports creating a whitelist of networks, ensuring that legitimate VPN users can access authorized resources.

• User velocity

  User Velocity tracks the number of distinct users per IP. The threshold of the number of users per IP is based on a statistical learning of the organization's past behavior. The risk predictor learns the mean average number of distinct users per IP per unit of time (hour), and the standard deviation. The Risk Predictor then calculates the low, medium, and high thresholds of the number of users per IP for the organization.

• User-based risk behavior

  The user-based risk behavior predictor compares a transaction with the typical behavior of the specific user. For example, if a user accesses an application that they rarely use, user-based risk behavior detects an anomaly. User-based risk behavior is a machine-learning model that continuously updates. The machine-learning model characterizes abnormal activity as low, medium, or high risk.

• Geovelocity anomaly

  Users frequently sign on to the same application from multiple locations throughout the day. However, a time lapse between the current sign-on location and the previous location that is shorter than the time it would take to travel between the two points could indicate potentially suspicious activity. PingOne Protect analyzes location data to calculate if travel time between two session locations is physically possible. If the elapsed time is calculated to be impossible, the user can be prompted with step-up authentication or denied access. It also supports creating a whitelist of networks, ensuring that legitimate VPN users can access authorized resources.

• User location anomaly

  User Location Anomaly detects a user's login location and checks it against previously saved authentication locations. If an authentication attempt occurs at a location whose distance from the user's expected location is greater than the radius you defined, it is considered medium or high risk, depending on the extent of the deviation from the defined radius.

• Bot detection

  Analyzes multiple device and user behavior factors to detect non-human behavior, automated frameworks, and recorders during attempts to register or authenticate. This type of predictor requires use of the Signals (Protect) SDK.

• New device

  New device predictors allow your risk policy to take into account the risk associated with users trying to access applications from unknown devices or devices that have not been used for sign-on in the recent past.

  Note: If you plan to include a new device predictor in your risk evaluations, your authentication flow must provide information that can be used to identify individual devices. The best way to do this is to implement the PingOne Signals (Protect) SDK in your web and mobile applications. This can also be done by providing a persistent cookie as input.

• Suspicious device

  Checks for suspicious settings or mismatches between browser, operating system, and hardware attributes in order to detect situations such as emulators, superuser permissions, virtual machines, mirroring applications, and devices that have been tampered with. This type of predictor requires use of the Signals (Protect) SDK.

• Adversary-in-the-Middle (AitM)

  Adversary-in-the-Middle is a variant of Man-in-the-Middle attacks. In AitM, a malicious actor uses a reverse proxy to position themselves between a user and an online service in order to obtain user credentials and session tokens. This type of attack circumvents the protection usually provided by OTP-based multi-factor authentication, and is a common technique in phishing attempts. The predictor checks the domain name that the user is trying to access in order to identify AitM attacks. The AitM predictor requires use of the Signals (Protect) SDK.

• Email reputation

  Detects the use of disposable email addresses during registration. You can add the predictor to your risk policies, and you can also define a specific course of action if the result.recommendedAction field in the risk evaluation response indicates the use of a disposable email address.

• Traffic Anomaly

  Intended for detection of traffic anomalies in terms of variables such as users, devices, and sessions, the Traffic Anomaly predictor will eventually include a variety of rules, some of which you can select to enable or disable. Currently, the predictor detects situations where there are a large number of risk evaluations requested for a single user within a short period of time, and optionally can also detect situations where the number of users per device during a given period is suspicious. When this predictor returns a value of High, it is recommended that you deny access because the suspicious activity is likely due to malicious behavior.

• PingID Device Trust

  The PingID Device Trust predictor checks if a device is trusted by validating the trust created during the installation of the PingID Device Trust agent. Requires use of the Signals (Protect) SDK and that the agent be installed on user computers.

• Custom risk predictors

  You can create custom predictors to assign high, medium, or low risk level based on external data that you provide or data that is accessible via the PingOne API but not included in the out-of-the-box predictor types.

In addition to the standard risk predictors, each of which represents a single risk factor, you can create composite risk predictors for situations where you are interested in combining a number of risk factors into a single predictor. For example, a situation where you are concerned about the use of an anonymous network only in cases where a user location anomaly is also reported.

Risk predictor evaluations

The evaluatedPredictors property in the policy set identifies the list of predictors (by ID) to be evaluated. If there is not enough data to assess a predictor level, the evaluation result does not assign any level to the predictor. In these cases, the response returns a Not enough information to assess risk score message.

When a predictor is added to a policy, regardless of the predictor weight, the predictor is evaluated when the policy is evaluated and its output appears in the details section of the risk service response. If you set the risk predictor's weight to 0, this predictor is evaluated but its risk assessment is not taken into account when calculating the risk score. Conversely, if the predictor is not added to the evaluatedPredictors property, or it was removed from the policy before evaluation, then the predictor is not evaluated and its output does not appear in the details section of the response.

Base risk predictor data model

Composite risk predictor data model

Traffic anomaly risk predictor data model

Velocity risk predictor data model

Risk predictors events generated

Refer to Audit Reporting Events for the events generated.

Custom risk predictors

You can define three types of custom risk predictors:

• IP Range - for custom handling of IP-related risks
• String Matching - definition of risk levels associated with different values of custom input provided as a string
• Numeric Range - definition of risk levels associated with different values of custom input provided as a number

While different fields are used for defining these three types of conditions, the basic JSON structure for the body of the request is similar for all types:

• The top-level field type must be set to MAP.
• The conditions are contained inside objects called map.high, map.medium, and map.low. You do not have to include all three levels, you just have to include at least one of these objects. If you include more than one level, for example, map.high and map.medium, each must refer to the same variable, for example, ${details.country}.
• The contains field in the condition can use any of the following as the variable whose value is being checked:
  • Any field in the details object (refer to Risk Evaluations)
  • Any field in the event object (refer to Risk Evaluations)
  • Any custom attribute added to the event object simply by adding the attribute to the event object in the body of a risk evaluation request

IP Range custom predictor - sample request body

{
  "name": "Device IP - custom",
  "compactName": "deviceIpCustom",
  "map": {
    "high": {
        "ipRange": [
            "1.1.1.1/5",
            "2.2.2.2/8"
        ],
    "contains": "${event.ip}"
    }
  },
  "type": "MAP",
  "default": {
    "result": {
      "level": "MEDIUM"
    }
  }
}

String Matching custom predictor - sample request body

{
  "name": "Device country - custom",
  "compactName": "deviceCountryCustom",
  "map": {
    "high": {
        "list": [
            "Iran",
            "Syria"
        ],
    "contains": "${details.country}"
    },
    "medium": {
        "list": [
            "Ethiopia",
            "Russia"
        ],
    "contains": "${details.country}"
    }
  },
  "type": "MAP",
  "default": {
    "result": {
      "level": "MEDIUM"
    }
  }
}

Numeric Range custom predictor - sample request body

{
  "name": "Device Network Location",
  "compactName": "deviceNetworkLocation",
  "map": {
    "high": {
      "between": {
        "minScore": 804672,
        "maxScore": 12742000
      },
      "contains": "${details.device.estimatedDistance}"
    },
    "medium": {
      "between": {
        "minScore": 321869,
        "maxScore": 804672
      },
      "contains": "${details.device.estimatedDistance}"
    },
    "low": {
      "between": {
        "minScore": 0,
        "maxScore": 321869
      },
      "contains": "${details.device.estimatedDistance}"
    }
  },
  "type": "MAP",
  "default": {
    "result": {
      "level": "LOW"
    }
  }
}

Composite risk predictors

The JSON content below shows the body of a request for creating a composite predictor.

Details to note about the content of the request body:

• type must be set to COMPOSITE.

• Each of the objects in the compositions array contain a condition object, which is use to specify the set of conditions to test, and the level field, which specifies the risk level that should be assigned if the conditions are met.

• The compositions array can contain a maximum of three elements.

• The specific predictor comparisons to carry out should use the ${details.*.level} format to specify the predictor to use. The string between details and level should be the compact name of the predictor.

• In addition to standard and custom predictors, you can include the following risk factors in composite predictors: country (${details.country}), state (${details.state}), IP range (${event.ip}), IP domain organization (${details.ipAddressReputation.domain.organization}), ISP (${details.ipAddressReputation.domain.isp}), target resource (${event.targetResource.name}), user ID (${event.user.id}), and user name (${event.user.name}). When creating conditions with these risk factors, you can use the following comparisons:

  • equals
  • notEquals
  • contains - to check if a value is in a defined list or in an IP range
  • notContains - to check if a value is not included in a defined list or in an IP range
  • startsWith - to check if a value begins with the specified string. Can be used with ISP, IP domain organization, user ID, and user name.
  • endsWith - to check if a value ends with the specified string. Can be used with ISP, IP domain organization, user ID, and user name.
  • containsIgnoreCase - to check if a value contains the specified substring, not case-sensitive. Can only be used for user ID and user name.

• In your composite predictors you can also include conditions that check what user groups the user belongs to. For user groups conditions, the comparisons to use are contains and notContains.

• Use ${details.counters.predictorLevels.high}, ${details.counters.predictorLevels.medium}, and ${details.counters.predictorLevels.low} to specify criteria relating to the number of predictors in a policy that yield a high, medium, or low risk result. For criteria of this type, use the relational terms equals, greater, lower, greaterEquals, lowerEquals.

• Within condition objects, use or for the array of conditions if it is enough for any of the conditions to be true, and and if all the criteria must be true. If none of the criteria can be true, construct an or array, then enclose it in a not object.
  
  Example of or:

"compositions": [
  {
    "condition": {
      "or": [
        {
          "equals": 3,
          "value": "${details.counters.predictorLevels.high}",
          "type": "VALUE_COMPARISON"
        },
        {
          "equals": "HIGH",
          "value": "${details.anonymousNetwork.level}",
          "type": "VALUE_COMPARISON"
        },
        {
          "type": "STRING_LIST",
          "list": [
            "Italy",
            "Germany"
          ],
          "notContains": "${details.country}"
        }
      ]
    },
    "level": "HIGH"
  }
]

Example of not:

"compositions": [
  {
    "condition": {
      "not": {
        "or": [
          {
            "value": "${details.counters.predictorLevels.high}",
            "equals": 3,
            "type": "VALUE_COMPARISON"
          },
          {
            "value": "${details.anonymousNetwork.level}",
            "equals": "high",
            "type": "VALUE_COMPARISON"
          },
          {
            "list": [
              "ITALY",
              "GERMANY"
            ],
            "notContains": "${details.country}",
            "type": "STRING_LIST"
          }
        ]
      }
    },
    "level": "HIGH"
  }
]

Full composite predictor example:

{
    "name": "Composite - anonymous network and country",
    "compactName": "compositeAnonymousAndCountry",
    "licensed": true,
    "compositions": [
        {
            "condition": {
                "or": [
                    {
                        "equals": 3,
                        "value": "${details.counters.predictorLevels.high}",
                        "type": "VALUE_COMPARISON"
                    },
                    {
                        "equals": "HIGH",
                        "value": "${details.anonymousNetwork.level}",
                        "type": "VALUE_COMPARISON"
                    },
                    {
                        "type": "STRING_LIST",
                        "list": [
                            "Italy",
                            "Germany"
                        ],
                        "notContains": "${details.country}"
                    }
                ]
            },
            "level": "HIGH"
        },
        {
            "condition": {
                "and": [
                    {
                        "equals": "HIGH",
                        "value": "${details.userLocationAnomaly.level}",
                        "type": "VALUE_COMPARISON"
                    }
                ]
            },
            "level": "MEDIUM"
        }    
    ],
    "type": "COMPOSITE",
    "default": {
        "weight": 5,
        "score": 50,
        "result": {
            "level": "LOW",
            "type": "VALUE"
        }
    }
}

Deleting risk predictors

If you want to start building your own workflows with PingOne APIs, the Workflow Library provides step-by-step workflows with linked Postman collections to help you start using the PingOne APIs in your Postman environment. For information about how PingOne secures APIs, resources, and data, and what you can do to implement security measures for your PingOne deployment and applications, refer to Platform security.

PingOne API domains

This section discusses how PingOne API regional endpoints are entered in the domain name system (DNS). In DNS, and in our endpoints, the domain part of the uniform resource locator (URL) comprises three parts separated by periods, such as api.pingone.com: one of our service-specific subdomains, our PingOne domain name of pingone, and one of our top level domains.

We use Postman variables to manage this variety of domain parts in PingOne API endpoints. The later discussion is correct regarding the domain part that the variables evaluate to. However, to ease maintenance, the Postman environment template you get when you download a collection uses variables to isolate the TLD from the rest of the domain part and to isolate the domain part from the rest of the endpoint.

The environment template has a path variable for each subdomain. Each path variable uses another variable, {{tld}}, for the top level domain (TLD). Such as https://api.pingone.com/v1 for {{apiPath}}. The tld variable is first in the environment template that you downloaded.

The table below shows the top level domain value for each region. To change your region, simply change the default {{tld}} value from com to your region's TLD.

The PingOne API includes the following domains:

The {{...Path}} variable in the sample requests stand for the PingOne service endpoint. Refer to Public endpoints in the PingOne for Developers Foundations guide for more information.

The Try a Request feature

Our documentation for the PingOne APIs includes an interactive Try a Request feature. Try a Request enables you to configure and send a PingOne API request and get a response from within the documentation. This is a quick way to interactively test a PingOne API request without needing to use either Postman or the command line.

Requests in Authentication and Authorization APIs do not have the Try a Request feature due to a Cross-Origin Resource Sharing (CORS) constraint.

Calling the PingOne APIs from the command line

Each PingOne API request in the documentation includes an example request and response. By default, the example request is displayed using cURL. However, a number of coding languages are available in the associated drop-down list. If you want to run a request from the command line, you can select the coding language and copy the displayed request. You'll need to replace any variables in the request with the appropriate values before running the request.

Using Postman collection-level authorization

Most APIs require authorization to ensure that client requests access data securely. Postman can pass along whatever authorization details necessary for the method demanded by the endpoint. You can manually include authorization data in the header, body, or as parameters to a request. However, the easiest way is to use the Authorization tab in Postman. Select an authorization Type on that tab and Postman offers a dialog to gather the information required by that Type. When you run a request, Postman uses the information from the Authorization tab to automatically add the necessary authorization header, body, or parameters to the request. Postman offers the Authorization tab on requests, folders, and collections.

In PingOne collections, the authorization method is defined at the collection level. Only those requests that require a specific authorization method have authorization defined on the request (roughly 10% of PingOne requests). This allows you to easily change the authorization used for most requests. Refer to Postman Collection-Level Authorization for more information.

We use Postman to create our PingOne DaVinci Admin API docs, and have supplied our Postman collections for you to download. There's also an accompanying Postman Environment template already populated with the variables used in the collections.

If you aren't currently using Postman, you can install the free version. Refer to Download Postman to install Postman, either locally, or in your browser.

Refer to The PingOne DaVinci Admin API Postman collections for the collections you can download or fork.

For more information about our Postman environment variables, refer to The PingOne Postman environment template.

You'll also find all of the Postman collections for our documented PingOne use cases in our Workflow Library.

You can get the PingOne Protect API Postman collection by following either of these methods for retrieving a Postman collection into your workspace:

1. Fork the collection into your workspace. Postman retains an association between the source and your fork. If we update the source collection, you can pull those changes into the fork in your workspace.

2. Import the collection into your workspace. This is a one-time transfer and retains no association to the source collection.

To retrieve a collection

Refer to The PingOne Protect API collections on this page.

1. Click the collection's Run In Postman button.

2. At the prompt, click Fork Collection at the bottom of the dialog or click import a copy near the bottom of the dialog.

   Note: You need to be logged in to your Postman account to retrieve the collection.

   

3. Follow the on-screen instructions to fork or import the collection. You're prompted to select a Postman workspace for the retrieved collection.

When you fork a Postman collection, you create a copy of it in a selected workspace. Forking a collection creates a linked version that synchronizes with its source collection. This synchronization is apparent when you click the three dots icon on the forked collection - you'll see Pull changes on the context menu. When you click Pull changes, Postman compares the fork to the source collection. If changes are available, you can pull those changes into your fork. If you also elect to watch the collection, you'll receive notifications when the source changes.

If you import a collection, a copy is created in the selected workspace with no link back to the source. The collection is static. This may be desirable for some use cases. For example, if you intend to keep and use only some requests in a collection, a link back to the source is not needed.

You're not limited to choosing one method or the other. You can fork a copy to track the source and import a copy for experimentation, if you like.

The PingOne Protect API collections

These Postman collections include requests for all create, read, update, and delete (CRUD) operations for the PingOne Protect APIs.

Collection	Description	Retrieve
PingOne Protect	Postman requests for the PingOne Protect Admin API. Includes all environment variables. No example responses to make it easy to get started.
PingOne Protect	Postman requests for the PingOne Protect API. Includes all PingOne Platform API Reference documentation and example responses. No environment variables are included.

For more information about the Postman environment variables included when you download or fork one of our Postman collections, refer to The PingOne Postman environment template.

Our Postman collections use variables in the request URLs to specify the UUIDs for PingOne resources. When you click the Run in Postman button for a collection, these environment variables are included in your download or fork. Use these environment variables as a template to assign your PingOne resource UUIDs with the common variables used in many of the requests.

For more information about using Postman environments, refer to the following topic in the Postman documentation: Environments in Postman.

POST requests in the PingOne Protect API Postman collections that create a resource and return a resource ID include a Postman script. This script automatically adds a resource variable to your active Postman environment, and uses the newly created ID as the value.

For example, the following request creates a new Protect variable. This request URL contains variables for the API path and environment ID:

POST {{apiPath}}/environments/{{envID}}/variables

To run this request, you must ensure the {{apiPath}} in the Postman environment template has the regional top-level domain (TLD) associated with your organization. Refer to Variables you must value for more information.

Almost every request in PingOne requires an environment ID. If you are working primarily in one environment for testing purposes, you'll want to add your environment's UUID to your active Postman environment as the value for the {{envID}} variable.

Requests to PingOne Management API endpoints require a valid access token to authenticate the request. In the PingOne Postman collections, the token value is represented in the Postman environment template as the variable {{accessToken}}.

With the {{tld}} and {{envID}} variables defined in your Postman template, and with a valid token value defined in the {{accessToken}} variable, you can run the request shown above:

POST {{apiPath}}/environments/{{envID}}/variables

If the request is successful, Postman adds a {{variableID}} variable to the current Postman environment automatically, and associates the new user's id property value (the UUID of the new user) with this variable.

Notes about environment variables and security

It's important to understand how Postman allows you to Store and reuse values using variables. Postman has two values for each environment variable: an Initial value and a Current value. You'll want to pay particular attention to differences between Initial and current values. Initial values are saved to Postman's cloud, and available to anyone who has access to the environment. Current values are saved only locally and available only to you. Postman uses only the current value in requests. If an environment variable has an initial value but no current value, Postman doesn't copy it to the current value or use the initial value in the request, the request simply fails. In this case, you need to manually copy the initial value to the current value.

When you create a new variable with an initial value and save the environment, Postman autofills the current value. However, that is the only time that Postman autofills the current value. If you subsequently delete the current value, the variable is no longer valued in a request.

Saving initial values to the Postman cloud impacts security. These initial values are available to anyone who has access to the workspace. If a workspace is public, you have a security issue.

Postman's recommended solution to exposing secrets is to Store secrets in your Postman Vault. Remember that Postman uses only current values in requests.

Variables you must value

When you download or fork a PingOne Postman collection, your workspace receives a set of Postman environment variables for you to use as a template. The variables that represent a resource in PingOne automatically receive a value when you create a new PingOne resource using Postman. Our script associated with the request (shown on the request's Scripts tab) inserts the identifier of the resource it creates as the value of the variable associated with that resource. However, some variables essential to using Postman with PingOne do not have their values inserted automatically. You must manually add the correct value to these variables before making any requests in Postman: