The risk service provides operations to retrieve risk evaluations from internal and external risk providers based on a specified risk policy. The risk policy is determined by the customer’s specific configuration settings as well as intelligence gathered from common use cases, which are then used in event evaluation to calculate risk scores for received events.

Risk evaluation data model

Property Description
createdAt The time the resource was created (format ISO-8061).
details A details object that provides additional information about the risk evaluation.
environment.id A string that specifies the environment resource’s unique identifier.
event An object that specifies the attributes to identify the event. This is a required property. For more information about event attributes, see the Event Data Model table.
id A string that specifies the resource’s unique identifier.
riskPolicySet.id A string that specifies the risk policy set resource’s unique identifier. If the risk policy set ID and name are both specified, the policy set specified by the riskPolicySet.id is used. If the risk policy set ID and name are not specified, the environment’s default risk policy set is used.
riskPolicySet.name A string that specifies the risk policy set name associated with this risk evaluation resource. If the risk policy set ID and name are both specified, the policy set specified by the riskPolicySet.id is used. If the risk policy set name and ID are not specified, the environment’s default risk policy set is used.
result A result object that specifies the result that corresponds to the risk policy that evaluates as true. If there are several risk policies that evaluate as true, the result that corresponds to the highest priority risk policy is returned. If no risk policy evaluates as true, the result is the defaultResult of the policy set.
updatedAt The time the resource was last updated (format ISO-8061).

Event data model

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

Property Description
browser An object that specifies the browser fingerprint attributes. Attributes are: userAgent, language, colorDepth, deviceMemory, hardwareConcurrency, screenResolution, availableScreenResolution, timezoneOffset, timezone, sessionStorage, localStorage, indexedDb, addBehaviour, openDatabase, cpuClass, platform, plugins, webglVendorAndRenderer, webgl, adBlock, hasLiedLanguages, hasLiedResolution, hasLiedOs, hasLiedBrowser, touchSupport, fonts, audio. Browser data can be retrieved using browser fingerprint JS. For more information, see Overview of the PingOne Risk Integration Kit.
completionStatus A string that specifies the state of the transaction. Options are FAILED, IN_PROGRESS, and SUCCESS. If a value is not provided, the value defaults to IN_PROGRESS. The value of this property can be changed only if its current state is IN_PROGRESS.
evaluatedFactors.status A string that specifies the state of the transaction. Options are FAILED, IN_PROGRESS, and SUCCESS.
evaluatedFactors.type A string that specifies the transaction type.
ip A string that specifies the origin IP address of the authentication flow. This is a required property.
flow.type A string that specifies the flow type for the event. The only option (and default) is AUTHENTICATION.
origin A string that specifies the calling service.
session.id A string that specifies a unique session ID associated with the event.
targetResource.id A string that specifies the ID of the target application.
targetResource.name A string that specifies the name of the target application.
user.id A string that specifies the ID of the user associated with the event (maximum size: 1024 characters). This is a required property.
user.name A string that specifies the name of the user associated with the event (maximum size: 1024 characters).
user.type A string that specifies the type of user associated with the event. Options are EXTERNAL. This is a required property.
user.groups An array of group names.
user.groups.name A string that specifies the name of the group (maximum size: 1024 characters).
sharingType A string that specifies the device sharing type. Options are UNSPECIFIED, SHARED, and PRIVATE.

Details data model

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

Property Description
ipAddressReputation.level A string that specifies the risk level of the evaluated IP address. Options are LOW, MEDIUM, and HIGH. If the score is less than 55, the level is LOW; if the score is greater than 77, the level is HIGH; if the score is between 55 and 77, the level is MEDIUM. Note that these guidelines could change based on data analytics and product consideration. If the ipAddressReputation.score is unknown, NULL is returned.
ipAddressReputation.score An integer that represents the calculated score of the IP address involved in the transaction. Scores range between 0 and 100. A score of 0 indicates a non-risky IP address; a score of 100 indicates a high-risk IP address. If the IP address reputation score is not available for the specific IP address, NULL is returned.
ipVelocityByUser.level An enum indicating whether the number of distinct IPs for the user in the past hour is flagged as LOW, MEDIUM, or HIGH.
ipVelocityByUser.reason A string indicating the reason the user was flagged. For example: “More than 13 IPs were accessed by John during the last 1 hour.”
ipVelocityByUser.threshold The information about the threshold used.
  • high. An integer indicating the value calculated for the high threshold. If the user accessed more than the high number of IPs during the past hour, they’re flagged as a HIGH ipVelocityByUser.level.

  • medium. An integer indicating the value calculated for the medium threshold. If the user accessed more than the medium number of IPs during the past hour, they’re flagged as a MEDIUM ipVelocityByUser.level.

  • source. An enum indicating the source used to calculate the threshold. This can be:
    • MIN_NOT_REACHED. If the measure is less than every.minSample, the threshold isn’t calculated. Instead, a value of LOW is automatically assigned. If less than five IPs were used by the user during the past hour, MIN_NOT_REACHED is set.

    • CALCULATED. Indicates the threshold is guaranteed to be calculated.

    • ENVIRONMENT_FALLBACK. Indicates a global threshold calculated for the entire environment is used. The global threshold is used when the ipVelocityByUser.threshold couldn’t be calculated, generally due to a lack of past transactions for the risk predictor to use for the threshold calculation.

    • DEFAULT_FALLBACK. Indicates the default threshold defined for the predictor (in threshold.medium or threshold.high) is used. The default threshold is used when ENVIRONMENT_FALLBACK (the global threshold) couldn’t be calculated, generally due to a lack of past transactions for the risk predictor to use for the environment threshold calculation.

  • calculatedAt. A date-time indicating the timestamp for the calculated threshold.

  • expiresAt. A date-time indicating when the threshold will be recalculated. The recalculation will happen before this time.
ipVelocityByUser.velocity Integer values for the measures used to calculate velocity.
  • distinctCount. This is the distinct count for the previous seconds indicated by the during value.

  • during. The interval (in seconds) during which the velocity is calculated.
userVelocityByIp.level An enum indicating whether the calculated number of users per IP is LOW, MEDIUM, or HIGH.
userVelocityByIp.reason A string indicating the reason the user was flagged. For example: “More than 250 users accessed IP address 1.1.1.1 during the last 1 hour.”
userVelocityByIp.threshold The information about the calculated threshold used.
  • high. An integer indicating the value calculated for the high threshold. If the IP was accessed by more than the high number of users during the past hour, the IP is flagged as a HIGH userVelocityByIp.level.

  • medium. An integer indicating the value calculated for the medium threshold. If the IP was accessed by more than the medium number of users during the past hour, the IP is flagged as a MEDIUM userVelocityByIp.level

  • source. An enum indicating the source used to calculate the threshold. This can be:
    • MIN_NOT_REACHED. If the measure is less than every.minSample, the threshold isn’t calculated. Instead, a value of LOW is automatically assigned.

    • CALCULATED. Indicates the threshold was calculated.

    • ENVIRONMENT_FALLBACK. Indicates a global threshold calculated for the entire environment is used. The global threshold is used when the userVelocityByIp.threshold couldn’t be calculated for the user, generally due to a lack of past transactions for the risk predictor to use for the threshold calculation.

    • DEFAULT_FALLBACK. Indicates the default threshold defined for the predictor (in threshold.medium or threshold.high) is used. The default threshold is used when ENVIRONMENT_FALLBACK (the global threshold) couldn’t be calculated, generally due to a lack of past transactions for the risk predictor to use for the global threshold calculation.

  • calculatedAt. A date-time indicating the timestamp for the calculated threshold.

  • expiresAt. A date-time indicating when the threshold will be recalculated. The recalculation will happen before this time.
userVelocityByIp.velocity Integer values for the measures used to calculate velocity.
  • distinctCount. Relevant only for predictors having a measure value of “DISTINCT_COUNT”. This is the number of users that accessed the IP in the past during seconds.

  • during. The interval (in seconds) during which the velocity is calculated.
impossibleTravel A boolean that specifies whether the distance between the location of the user in their previous successful authentication and current authentication infers that the user had to travel at a speed greater than 1000 kilometers per hour. This condition is marked as fulfilled, only if:
  • Location data is available for the current and previous IP address of the user.
  • This is not the first transaction that the user has performed.
  • The user’s previous successful transaction was performed less than 24 hours ago.
  • The user moved a distance of at least 100 kilometers. Thus, even if the user moved very fast, but moved only a distance of 90 kilometers, the condition is not fulfilled.
  • The user moved at a speed greater than 1000 kilometers per hour.
.
estimatedSpeed The calculated travel speed in units of kilometers per hour.
anonymousNetworkDetected A boolean that specifies whether the current authentication originated from an anonymous network (for example, proxy or VPN).
country A string that specifies the country related to current transaction from the IP address.
longitude A double-precision floating point that specifies the longitude related to current transaction from the IP address. Values range from -90 to 90.
latitude A double-precision floating point that specifies the latitude related to current transaction from the IP address. Values range from -180 to 180.
previousSuccessfulTransaction.anonymousNetworkDetected A boolean that specifies whether an anonymous network was detected. Information is available twenty-four hours after the last successful transaction.
previousSuccessfulTransaction.country A string that specifies the country of the IP address involved in the transaction. Information is available twenty-four hours after the last successful transaction.
previousSuccessfulTransaction.ip A string that specifies the IP address involved in the transaction. Information is available twenty-four hours after the last successful transaction.
previousSuccessfulTransaction.timestamp A date that specifies the timestamp of the transaction. Information is available twenty-four hours after the last successful transaction.
userRiskBehavior.level A string that specifies the risk score calculated for the user behavior associated with the accessing device, for the current authentication attempt. Options are LOW, MEDIUM, and HIGH. This information is available only if customers have agreed to data consent and the intelligence.allowDataConsent property in the PingOne license is set to true.
userRiskBehavior.reason A string that describes the reason (or reasons) provided for the user behavior risk score classification (for example, the operating system or browser type used by the device, and country in which the accessing device is located). Each reason is classified as Unusual or Very Unusual, to indicate how much it deviates from normal user behavior, and its effect in calculating the overall user behavior risk score.

Result attribute data model

The result property returned by a POST request includes the following attributes for the specified event.

Property Description
type A string that specifies the risk evaluation result type. Options are VALUE.
level A string that specifies the risk evaluation result level. Options are HIGH, MEDIUM, and LOW.
value A string that specifies any custom attribute the administrator defines.

Response codes

Code Message
200 Successful operation.
201 Successfully created.
400 The request could not be completed.
401 You do not have access to this resource.
403 You do not have permissions or are not licensed to make this request.
404 The requested resource was not found.