Recommendations

You can get a risk recommendation for a sensitive action your users want to perform in a risk moment in order to assess the risk level and respond with the suggested mitigation strategy when needed. Detection and Response code snippets are used to report telemetry and user actions, and you can obtain a recommendation for any action you reported using the Recommendations API. This describes the various recommendations that may be returned, and how you'd use them to protect accounts based on the use case.

Action types

You can ask for recommendations for the following types of actions, performed as part of the customer journey:

  • login
  • register
  • transaction
  • checkout
  • password_reset
  • logout
  • account_details_change
  • account_auth_change
  • withdraw
  • credits_change

Recommendation types

Recommendations tell you how to respond to your user's request to access your application. We create them in real-time by applying our advanced, ML-driven detection capabilities to the given context. This allows us to suggest an accurate approach that protects both your application and the user experience. It also means that we handle all the complexity, so all you need to do is act according to the recommendation we provide.

The following types of recommendations may be returned:

Type Description
trust Trust the activity, extend the session and lower friction (e.g., by not requiring two-factor authentication). This isn't returned in the context of unknown users and devices (e.g., password reset or registration) since it usually relies on data collected over time.
allow Low risk and so no risk mitigation is needed; proceed with the regular flow.
challenge Risk mitigation is required by providing an appropriate challenge based on the use case
deny There's a high risk of malicious activity. Don't proceed with the action, and return a generic error message since you don't want to provide any info the attacker can use to adapt their approach or further their attack.

Challenges

Risk mitigation can be performed by providing a challenge to the user that elevates the trust. Different challenges are more suitable for different use cases. Below are some examples of how you can challenge users based on the action they want to perform.

Action Challenge
login Second-factor authentication (preferably using strong biometrics).
register Additional means such as ID verification or even an offline manual review.
checkout Second-factor authentication (preferably using strong biometrics), revoke payment method for credit cards or third-party payment providers, re-enter CVV for cards on file, 3DS for transactions based on credit cards, ID verification for high-security cases, or manual review for high-cost checkout
password_reset Email or SMS verification, or have the user contact a Call Center to manually review

Reasons

Along with the recommendation, reasons are provided to explain why the recommendation was returned and provide transparency. The prefix of the reason indicates the category of reason, and not every reason is applicable to each action and use case. The reasons are relevant for all platforms (Web, Android, iOS) unless stated otherwise.

Note

Recommendations are all you need to make your decisions. You don't need to act on the reasons.

Here are some examples of reasons that may be provided (which may change over time):

Reason Description
BEHAVIOR_BOT Indicates bot activity, such as very fast typing speed or no mouse movement before clicks.
BEHAVIOR_SUSPICIOUS_ATTR Indicates suspicious behavior, such as no apparent input during text insertion or copy-pasting.
DEVICE_ACTION_VELOCITY A high number of actions per time period detected on the device, which indicates abnormal or bot activity.
DEVICE_BOT Indicates bot activity, such as use of a headless web browser or automated interactions.
DEVICE_COOKIE_REUSED Indicates cookie hijacking as an identical device ID was sent from more than one device.
DEVICE_EMULATOR Indicates that a device emulator is being used, such as unexpected mobile attributes or the browser attributes do not match the device's OS.
DEVICE_OLD_VERSION An old, less secure browser version is being used.
DEVICE_ROOTED (iOS and Android only) Indicates that a device has been unlocked and jailbroken to allow access to its configuration.
DEVICE_SPOOFED The device is being spoofed (trying to hide its real identity), as indicated by the use of a modified user agent.
DEVICE_SUSPICIOUS_ATTRIBUTE A suspicious device attribute was detected, such as browser attributes that do not match the device's graphic card.
DEVICE_SUSPICIOUS_NETWORK The browser's timezone does not match the timezone of the source IP's country, which may indicate browser location spoofing.
DEVICE_SUSPICIOUS_VELOCITY Two or more users are using the same device.
DEVICE_TAKEOVER Indicates that a device is being controlled remotely, such as anomalies in user interactions.
DEVICE_TAMPERED (iOS and Android only) Indicates that a device software or hardware has been modified, for example, cloaning apps are deployed or a device has been rooted.
DEVICE_VM Indicates use of a VM, such as when an emulated GPU is detected, there are an odd number of device cores, or the device's screen resolution is unusual.
IP_ACTION_VELOCITY A large number of actions originated from the same IP.
IP_COUNTRY_BLOCKED The device's IP is from a blocked country.
IP_IS_BIZ The device's IP is registered to a business organization.
IP_IS_VPN The device might be using a VPN.
IP_RISKY_REPUTATION Indicates a suspicious IP, such as use of the Tor network or IPs regarded as unsafe.
PROFILE_ACTIVITY_ANOMALY The user activity is considered anomalous for the user’s profile.
PROFILE_DEVICE_ANOMALY The device attributes are considered anomalous for the user’s profile.
PROFILE_DEVICE_FAMILIAR The device is considered to be familiar (for the user profile).
PROFILE_DEVICE_FAMILIAR_MODEL The device model (for example, iPhone 13) is considered to be familiar (a new device that is the same model as a known user's previous device).
PROFILE_DEVICE_NEW The device is considered to be new (for the user profile).
PROFILE_IMPOSSIBLE_TRAVEL The device's location changed faster than possible, for example, a device is located in the UK 15 minutes after it was located in the US.
PROFILE_IP_FAMILIAR The device's IP is considered to be familiar (for the user profile).
PROFILE_LOCATION_ANOMALY The user location is considered anomalous for the user’s profile.
PROFILE_LOCATION_NEW The device's location (determined by IP) is considered to be new.
PROFILE_NETWORK_ANOMALY The user network is considered anomalous for the user’s profile.

Risk signals

Risk signals provide insights on specific indicators such as a proxy or VPN connection being used. You can check what indicators have been verified as well as their state. Unlike reasons that take into account a combination of telemetry data, signals are discrete and focus on specific risk factors.

Note

Recommendations are all you need to make your decisions. You don't need to act on the risk signals.

Example

Here's an example of a challenge recommendation:

Copy
Copied
{
  "id": "385cd06b527a974982e0560b67123fe2b1b5a39fd98d8d32cdbaca8ec16fd62d",
  "issued_at": 1648028118123,
  "recommendation": {
    "type": "challenge"
  },
  "risk_score": 73.2,
  "context": {
    "action_id": "885cd06b527a97498200560b67123fe221b5a39fd98d8d22cdb7ca8ec16ed62d",
    "action_type": "login",
    "action_performed_at": 1648028118123,
    "device_id": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIwZGE4ZmZjYy01NmE1LTRmMjgtYThkZi04NDY5MmYwYThmYTAiLCJ2ZXJzaW9uIjoxLCJpYXQiOjE2NTU3OTYzODQ1MzF9.TeGoqlCe_6eWzl9a3-vAumG4Xap8WjwsgcO2-DzGtLg",
    "device_fingerprint": "a3c8f5ea75cb65fcdc3d0452b985f957a46e24afdc912e93dac1e115ecf408e5",
    "user_id": "5c4afa75c",
    "application_id": "ece93f4",
    "device_timezone": "America/Los_Angeles",
    "device_platform": "desktop",
    "os_name": "macOS",
    "browser_name": "Chrome"
  },
  "risk_signals": {
    "device": {
      "incognito": false,
      "tampered": false,
      "emulated": true,
      "spoofed": false,
      "tz_mismatch": true
    },
    "network": {
      "vpn": false,
      "tor": true,
      "hosting": false,
      "proxy": true,
      "anonymizer": false
    },
    "behavior": {
      "typing_velocity": 0.867,
      "input_method": [
        "is_paste"
      ],
      "no_user_interaction": true
    }
  },
  "reasons": [
    "BEHAVIOR_BOT",
    "IP_RISKY_REPUTATION",
    "DEVICE_SUSPICIOUS_ATTRIBUTE",
    "PROFILE_DEVICE_NEW"
  ]
}