PingOne Platform APIs

Risk Evaluations

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.

Sample flow with 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

Property Type Required? Mutable? Description

createdAt

Date

N/A

Read-only

The time the resource was created (format ISO-8061).

details

Object

Optional

Mutable

Contains additional information about the risk evaluation. Refer to the following Details data model table.

environment.id

String

Required

Immutable

The environment resource’s unique identifier.

event

Object

Required

Mutable

Contains the attributes identifying the event. For more information about event attributes, refer to the following Event data model table.

id

String

N/A

Read-only

The risk evaluation’s unique identifier.

riskPolicySet.id

String

Optional

Mutable

The risk policy set’s unique identifier. If this property and riskPolicySet.name are both specified, the policy set referenced by this property is used. If neither this property nor riskPolicySet.name are specified, the environment’s default risk policy set is used.

riskPolicySet.name

String

Optional

Mutable

The risk policy set associated with this name. If this property and riskPolicySet.id are both specified, the policy set referenced by riskPolicySet.id is used. If neither this property nor riskPolicySet.id are specified, the environment’s default risk policy set is used.

riskPolicySet.targeted

Boolean

Optional

Immutable

Set riskPolicySet.targeted to true if you want the risk evaluation to process the targeted policies defined in the environment rather than using a specific policy. The targeted policies are processed until a policy is found whose conditions (transaction type, user group, application) are met.

result

Object

N/A

Read-only

Contains the risk policy that evaluates as true. If there are several risk policies that evaluate as true, the highest priority risk policy is returned. If no risk policy evaluates as true, the defaultResult of the policy set is returned.

result.level

String

N/A

Read-only

The risk evaluation result level. Options are HIGH, MEDIUM, and LOW.

result.recommendedAction

String

N/A

Read-only

The recommended course of action based on the evaluation. Currently used only for policies that include a bot detection predictor, an Adversary-in-the-Middle (AitM) predictor, an email reputation predictor, or a traffic anomaly predictor. If recommendedAction is included in the response, the possible values are:

  • ACCOUNT_RECOVERY, meaning that there are indications that the user’s account may have been compromised so you should have them follow your account recovery procedure.

  • AITM_MITIGATION, meaning that you should take steps to mitigate the damage from an AitM attack. For an AitM attack, the user’s credentials have been intercepted, so in addition to blocking the access request, you should lock the user’s account until the password is changed.

  • BOT_MITIGATION, meaning that you should take steps to handle a scenario where a bot is involved.

  • DENY - returned when a risk level of HIGH is calculated for a traffic anomaly predictor. The recommendation is that you deny access because the suspicious activity is likely due to malicious behavior.

  • TEMP_EMAIL_MITIGATION, meaning that the user has specified a disposable email address, so you should probably block the registration attempt.

result.type

String

N/A

Read-only

The risk evaluation result type. Options are VALUE, indicating any custom attribute that’s defined.

updatedAt

Date

N/A

Read-only

The time the resource was last updated (format ISO-8061).

Event data model

These properties specify information about events processed for risk evaluation.

The ip, user.id, and user.type properties are required. All other properties are optional. However, the service requires either the targetResource.name or targetResource.id property and the browser.userAgent property to perform user risk behavior modeling.
Property Type Required? Mutable? Description

browser.cookie

String

Optional

Mutable

To improve risk analysis, provide the value of a persistent cookie.

browser.userAgent

String

Optional

Mutable

The user agent string for the browser.

completionStatus

String

N/A

Read-only

Whether the flow completed successfully. For the various flow types, SUCCESS and FAILED represents the following:

  • AUTHENTICATION

    • SUCCESS: authentication completed and a session or token is issued.

    • FAILED: authentication did not complete (invalid credentials, step-up failed, user cancelled or abandoned)

  • ACCOUNT_RECOVERY / PASSWORD_RESET

    • SUCCESS: account recovery or password reset successful (user verified or reset completed)

    • FAILED: recovery did not complete (verification failed or user abandoned)

  • REGISTRATION

    • SUCCESS: account created

    • FAILED: account creation failed or abandoned

  • TRANSACTION

    • SUCCESS: transaction approved or committed

    • FAILED: transaction declined, failed, or abandoned

  • AUTHORIZATION

    • SUCCESS: action permitted and performed

    • FAILED: action denied or not completed

device

Object

Optional

Mutable

Contains information about the device being used.

device.externalId

String

Optional

Mutable

If you want to maintain your own device IDs, you can send the device ID to the risk evaluation by using device.externalId, and this is the ID that will be used rather than the device ID provided by the Signals SDK. One situation where you may want to use this approach is if your mobile native app incorporates a WebView. In such cases, the mobile Signals SDK and the web Signals SDK will provide different device IDs. By providing your own device ID, you’ll have a consistent device ID that can be used.

evaluatedFactors.status

String

Optional

Mutable

The state of the transaction. Options are FAILED, IN_PROGRESS, and SUCCESS.

evaluatedFactors.type

String

Optional

Mutable

The transaction type.

flow.type

String

Optional

Mutable

The type of flow for which the risk evaluation is being carried out. Can take any of the following values:

  • REGISTRATION - initial registration of an account

  • AUTHENTICATION - standard authentication for login or actions such as password change

  • ACCESS - verification of whether user can access the relevant application, using tools such as PingAccess

  • AUTHORIZATION - verification of whether user is authorized to perform a specific action such as a profile change, using tools such as PingOne Authorize

  • TRANSACTION - authentication carried out in the context of a purchase or other monetary transaction

The default value is AUTHENTICATION.

flow.subtype

String

Optional

Mutable

If you want to provide additional detail about the context of the flow, you can specify a subtype in addition to type. The values that can be used for subtype are:

  • AUTHENTICATION - ACCOUNT_RECOVERY, ACTIVE_SESSION, KERBEROS, NEO_CREDENTIALS, PASSKEY, PASSWORDLESS, USER_CERTIFICATION, USER_PASSWORD, USERNAME_RECOVERY

  • AUTHORIZATION - ADD_ADDRESS, ADD_MFA, ADD_PAYEE, ADD_PHONE_NUMBER, ADD_USER, CHANGE_PASSWORD, DELETE_MFA, DELETE_PAYEE, UPDATE_ADDRESS, UPDATE_PHONE_NUMBER

ip

String

Required

Mutable

The originating IP address of the authentication flow.

origin

String

Optional

Mutable

The calling service.

sdk

Object

Optional

Immutable

Object used to provide the data from the Signals (Protect) SDK.

sdk.signals.data

String

Optional

Immutable

The data collected by the Signals (Protect) SDK.

session.id

String

Optional

Mutable

The unique session ID associated with the event.

sharingType

String

Optional

Mutable

Whether a device is likely used by a single individual, or shared among multiple users.

Used to adjust risk interpretation and risk policy decisions. If not specified, risk engines may over-penalize normal behavior on shared devices, or under-estimate risk on private devices.

Options include UNSPECIFIED, SHARED, and PRIVATE.

targetResource.id

String

Optional

Mutable

The unique identifier representing the application, service, or resource the user is attempting to access or act upon.

This identifier is used for policy targeting, analytics, and consistent risk evaluation. For PingOne integrations, this value corresponds to the PingOne application ID. For non-PingOne integrations, define this value and ensure it is unique within your environment.

targetResource.name

String

Optional

Mutable

The name describing the target application or resource.

This name is intended for display, logging, and explainability purposes. The name does not need to be unique, and may change over time without affecting policy behavior.

user.groups

String[]

Optional

Mutable

The list of groups the user belongs to, representing organizational, role-based, or business-level classifications associated with the user.

Groups can be used as contextual signals for authorization, policy evaluation, risk assessment, and fraud detection. They allow decisions to be tailored based on the user’s role, privileges, or segment within an organization.

user.groups.name

String

Optional

Mutable

The name of a group associated with the user. Group names may represent roles, departments, access levels, or other organizational classifications.

user.id

String

Optional

Mutable

A unique, persistent identifier for the user that remains constant across events and time. This ID enables identity correlation, historical analysis, and consistent risk evaluation.

For EXTERNAL users, provide user.id and user.name. For PING_ONE users, provide user.id is available, and include user.name if it’s meaningful (for example, email address). For AITM, include user.name when it represents the login identifier.

user.name

String

Optional

Mutable

A human-readable identifier for the user, typically the username or login identifier (for example, an email address).

user.type

String

Required

Mutable

The type of user associated with the event. The possible values are PING_ONE and EXTERNAL.

Details data model

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

Property Type Required? Mutable? Description

anonymousNetworkDetected

Boolean

N/A

Read-only

Indicates whether the current authentication originated from an anonymous network (for example, proxy or VPN).

city

String

N/A

Read-only

The city related to the current transaction from the IP address.

country

String

N/A

Read-only

The country related to the current transaction from the IP address.

detected

Object

N/A

Read-only

Relevant only for Bot Detection predictors and Suspicious Device predictors. Contains the information on the rule that led to the level reported.

detected.rule.id

Integer

N/A

Read-only

Relevant only for Bot Detection predictors and Suspicious Device predictors. ID number of the rule that led to the level reported.

device

Object

N/A

Read-only

Contains information about the device being used.

device.agent

Object

N/A

Read-only

For risk evaluations that include the PingID Device Trust predictor, contains the data from the trust agent.

device.agent.customScript.exitCode

Integer

N/A

Read-only

If a local script was specified when installing the Workforce Trust agent on individual computers, will contain the exit code for the script.

device.agent.customScript.output

String

N/A

Read-only

If a local script was specified when installing the Workforce Trust agent on individual computers, will contain the output of the script.

device.agent.id

String

N/A

Read-only

The ID generated by the agent to identify the user’s computer.

device.agent.loggedInUser.domainName

String

N/A

Read-only

The domain name for the logged-in user.

device.agent.loggedInUser.name

String

N/A

Read-only

The name of the logged-in user.

device.agent.loggedInUser.objectSid

String

N/A

Read-only

The SID (security identifier) for the logged-in user.

device.agent.macAddress

Array

N/A

Read-only

The MAC addresses of the user’s computer.

device.agent.name

String

N/A

Read-only

The name of the user’s computer.

device.agent.os.name

String

N/A

Read-only

The operating system on the user’s computer.

device.agent.os.version

String

N/A

Read-only

The version of the operating system on the user’s computer.

device.agent.version

String

N/A

Read-only

The version of the trust agent.

device.estimatedDistance

Double

N/A

Read-only

The distance between the current location of the device and the location of the device when the last risk evaluation was carried out. Distance is given in meters.

device.externalId

String

N/A

Read-only

The externally-maintained device ID that was provided in the risk evaluation request, if such an ID was included. For more details, refer to the Event data model.

device.externalLastSeen

Date

N/A

Read-only

If an externally-maintained device ID was provided in the risk evaluation request, externalLastSeen is the date and time that device was last seen. Returned only if the risk policy used for the evaluation includes the New Device predictor.

device.id

String

N/A

Read-only

The device ID provided by the Signals (Protect) SDK.

device.lastSeen

Date

N/A

Read-only

The date and time the device was last seen. Returned only if the risk policy used for the evaluation includes the New Device predictor.

estimatedDistance

Double

N/A

Read-only

The distance between the user’s current location and the user location when a risk evaluation was last updated with the completion status SUCCESS. Distance is given in meters.

estimatedSpeed

Integer

N/A

Read-only

The speed the user would have had to travel at to reach their current location, based on the distance from the location when a risk evaluation for the user was last updated with the completion status SUCCESS and the time elapsed since that update event. Speed is given in kilometers per hour.

impossibleTravel

Boolean

N/A

Read-only

Indicates 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.

ipAddressReputation.domain.asn

Integer

N/A

Read-only

The autonomous system number.

ipAddressReputation.domain.isp

String

N/A

Read-only

The ISP that registered the domain.

ipAddressReputation.domain.organization

String

N/A

Read-only

The organization that owns the domain.

ipAddressReputation.domain.sld

String

N/A

Read-only

The second-level domain.

ipAddressReputation.domain.tld

String

N/A

Read-only

The top-level domain.

ipAddressReputation.level

String

N/A

Read-only

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

Integer

N/A

Read-only

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.

previousSuccessfulTransaction.anonymousNetworkDetected

Boolean

N/A

Read-only

Indicates whether an anonymous network was detected. Information is available twenty-four hours after the last successful transaction.

previousSuccessfulTransaction.city

String

N/A

Read-only

The city of the IP address involved in the transaction. Information is available twenty-four hours after the last successful transaction.

previousSuccessfulTransaction.country

String

N/A

Read-only

The country of the IP address involved in the transaction. Information is available twenty-four hours after the last successful transaction.

previousSuccessfulTransaction.ip

String

N/A

Read-only

The IP address involved in the transaction. Information is available twenty-four hours after the last successful transaction.

previousSuccessfulTransaction.state

String

N/A

Read-only

The state of the IP address involved in the transaction. Information is available twenty-four hours after the last successful transaction.

previousSuccessfulTransaction.timestamp

String

N/A

Read-only

The timestamp of the transaction. Information is available twenty-four hours after the last successful transaction.

state

String

N/A

Read-only

The state or province related to the current transaction from the IP address.

{{predictorCompactName}}.level

String

N/A

Read-only

The risk score calculated for the predictor-related transactions associated with the accessing device, and for the current authentication attempt. Options are LOW, MEDIUM, and HIGH.

{{predictorCompactName}}.reason

String

N/A

Read-only

The reason (or reasons) provided for the 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, to indicate how much it deviates from normal user behavior, and its effect in calculating the overall predictor risk score. Note that these messages may change in the future. If you want to take action based on a certain scenario, the action should be based on the value of detected.rule.id, which is constant.

{{predictorCompactName}}.status

String

N/A

Read-only

Additional information about the predictor evaluation outcome. Example responses are NOT_AVAILABLE, IN_TRAINING_PERIOD, or FAILED_TO_COMPUTE.

{{predictorCompactName}}.type

String

N/A

Read-only

The type of the predictor.

Update Risk Evaluation data model

Property Type Required? Mutable? Description

completionStatus

String

Required

Immutable

If the flow was completed successfully, set to SUCCESS. If not, set to FAILED. The value of this property can be changed only if its current state is IN_PROGRESS.

Risk evaluations events generated

Refer to Audit Reporting Events for the events generated.

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.

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

Property Type Required? Mutable? Description

evaluationFeedbackItems

Array

Required

Immutable

The collection of feedback items.

evaluationFeedbackItems[].feedbackCategory

String

Required

Immutable

One of the following categories of feedback: FALSE_HIGH_RISK, FRIENDLY_BOT, NEW_ACCOUNT_FRAUD, COMPROMISED_ACCOUNT, AUTOMATED_ATTACK.

evaluationFeedbackItems[].reason

String

Optional

Immutable

The reason that the specific feedback category was specified. The possible values depend upon the category chosen.

  • False high risk: OFFICE_NETWORK, COMPANY_VPN, WRONG_LOCATION, ORG_NETWORK, SUCCESSFUL_MFA, OTHER

  • Friendly bot: KNOWN_CRAWLER, KNOWN_AGGREGATOR, INTERNAL_AUTOMATION, OTHER

  • New account fraud: SUSPICIOUS_EMAIL_ADDRESS, USERNAME_GUESSING, OTHER

  • Compromised account: USER_CLAIMS_IT_IS_NOT_THEM, UNSUCCESSFUL_MFA, OTHER

  • Automated attack: CREDENTIAL_STUFFING, PASSWORD_SPRAY, OTHER

evaluationFeedbackItems[].riskEvaluation.createdAt

Date

Optional

Immutable

The date and time the risk evaluation was carried out. Use ISO-8061 format, for example, 2024-05-01T13:44:33.417Z. This parameter is optional, but providing a value for it makes the feedback process more efficient.

evaluationFeedbackItems[].riskEvaluation.id

String

Required

Immutable

The ID of the risk evaluation.

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