evaluateRisk response

The evaluateRisk response returns the status of the request to assess whether a particular sign-in event is considered risky.
evaluateRisk
output fields
lists details about the
evaluateRisk
output fields.
Data stored on the device (device tag) takes higher precedence for risk assessment when both the device tag and the device fingerprint (canvas fingerprint) are encoded in the
IAAuthData
key.
evaluateRisk
output fields
Output Field
Required?
Type
Purpose
requestId
Y
String
The
requestId
sent with the
evaluateRisk
request.
status
Y
hex string
Unique status code.
0000=Success
. Any other value is an error.
statusMessage
Y
String
Message corresponding to the status of the request. If the status is not
0000
(success), this message is an error message.
Risky
Y
Boolean
Returns "true" if a sign-in event is considered risky. Otherwise is "false."
RiskScore
Y
Double
An integer between 0 and 100, inclusive. The higher the value, the higher the risk of the particular sign-in event.
RiskThreshold
Y
Double
An integer between 0 and 100, inclusive. If the risk score exceeds the threshold, the sign-in event is considered risky.
RiskReason
Y
String
Reasons that contributed to the risk score or risk decision. Reasons increase the risk score, unless noted. Multiple reasons may appear in a single response.
  • Behavior anomaly: Request is made in manner inconsistent with previous behavior. For example, requests made from a new IP address, browser, or operating system from the requests used previously would be considered an anomaly. This response may indicate that the request is fraudulent, that the user is legitimately traveling, or that the user is logging on from a new or temporary device.
  • Blocked IP: Request is made from an IP on the challenged IP list uploaded to VIP Manager (
    Policies
    >
    VIP Intelligent Authentication
    >
    Challenged IP Addresses
    ). Reason may directly affect the risk decision.
  • Device Recognition: Request is made from a device that is not recognized, the recognition is incomplete, or the
    IAAuthData
    field was empty. This response may indicate that the request is fraudulent, or that the user is logging on from a new or temporary device. Check the
    device.registered
    key to verify if the device was registered for the user. Reason may increase or reduce the risk score, or directly affect the risk decision.
  • Device Reputation: The device was previously compromised or a victim of malware or other attack.
  • Enhanced Difficult travel: Two consecutive requests are made from IP addresses in locations sufficiently far apart that it would be unlikely for the user to travel quickly enough to arrive at the location of the second IP in the time period between the two transactions.
    For example, if a user logs on from New York and then logs on from Hong Kong 10 minutes later, the transaction could be a fraud since it is impossible to travel to Hong Kong from New York that quickly.
  • IPS: Request is made from an IP address that was recently targeted by an attack. This response may indicate that the IP address has been compromised.
  • Fraud IP: Request is made from an IP that is known to be compromised or fraudulent.
  • Previous event is confirmed risk: Request is made immediately following a request that is known to be a risk. Reason may directly affect the risk decision.
  • Remembered device expired: The device fingerprint has expired. The
    device.expired.reason
    key value provides more information.
  • Risky country: Request is made from an IP in a country that may pose a high risk.
  • Allowed IP: Request is made from an IP on the Accepted IP List uploaded to VIP Manager (
    Policies
    >
    VIP Intelligent Authentication
    >
    Accepted IP Addresses
    ). Reason may reduce the risk score, or directly affect the risk decision.
PolicyVersion
Y
String
Version of rules and values that are used for risk analysis.
EventId
Y
String
The ID of the current event generated by IA.
RequestContext
Y
String
More details from the request or about the request. Returned only if
IncludeRequestContext
is set to
true
in the request.
  • Ip
    : The IP address that is originally provided as part of the request.
  • UserAgent
    : The browser user agent information that is originally provided as part of the request.
  • IpLocation
    : The following location information derived from the IP address, if available:
    • Country
    • State
    • City
    • Latitude
    • Longitude
  • GpsLocation
    : The following location information derived from the mobile data for the device, if available:
    • Latitude
      : Latitude of the mobile device.
    • Longitude
      : Longitude of the mobile device.
KeyValuePair
N
List
A list of the key and value strings that are returned in the response. See
KeyValuePair
output fields
.
KeyValuePair
output fields
lists the key and value strings that are returned in the
KeyValuePair
output fields.
KeyValuePair
output fields
Output Field
Purpose
external.user.id
The
userId value provided in the
evaluateRisk
request. This field is useful for tracking the
evaluateRisk
request and response.
device.friendly.name
The unique name for the device provided by the user during registration. If the user registered the device without providing a friendly name, the default friendly name is used. Only returned if the user registered the device.
device.registered
Indicates whether IA recognizes the device as registered for the user. Value is either true or false. If false, IA determined that the device is not registered.
If the
evaluateRisk
request does not include valid
IAAuthData
, this value is always false.
device.tag
A unique tag to be stored on the device for the user to register it. Value is a string.
Only returned if valid
IAAuthData
is present in the request, and:
  • device.registered
    is false OR,
  • Risky
    response is
    false
    and the device match is a remembered device.
device.tag.id
A unique identifier for the device.
device.expired
Indicates if the device fingerprint is expired. Value is true or false.
device.expired.reason
Indicates the reason that the device fingerprint has expired:
  • DEVICE_EXPIRED_MAX_LIFE
    : The device fingerprint reached the expiration date (maximum life) set for the account. The user must use a second factor to authenticate with this device.
  • DEVICE_EXPIRED_NO_AUTH
    : The user has not used the device to successfully authenticate in the time frame set for the account. The user must use a second factor to authenticate with this device.
device.shared
Indicates if the device is shared by other users. Value is either true or false.
device.registered.reason
Indicates the reason that IA did or did not detect that the device is registered.
device.match.method
IA can identify if a specific device is registered to a user in one of two ways. During registration, VIP may store device identifying information in local storage on the client device, as a tag in the browser or device. IA may also use attributes of the device, such as the operating system, browser, or graphics capabilities (the device fingerprint) to identify the device. The device tag takes precedence when both device tag and device fingerprint (canvas fingerprint) are present in the evaluateRisk API call.
This field indicates the method that IA used when attempting to identify the device:
  • TAG_MATCH
    : IA identified the device using the device identifying information that is stored on the device.
  • TAG_INVALID
    : Device identifying information was found on the device, but it did not match the identifying information in the VIP system.
  • CANVAS_MATCH
    : No device identifying information was found on the device. IA Identified the device by the device fingerprint data (canvas fingerprint).
  • CANVAS_INVALID
    : No identifying information was found on the device. Device fingerprint data (canvas fingerprint) did not match the VIP data. The system did not have enough information to attempt an enhanced match.
  • ENHANCED_MATCH
    : No device-identifying information was found on the device. Device fingerprint data (canvas fingerprint) did not match the VIP data. IA Identified the device by an enhanced match of non-canvas attributes for the device.
  • ENHANCED_INVALID
    : No identifying information was found on the device. Device fingerprint data (canvas fingerprint and enhanced fingerprint) did not match the VIP data.
  • NONE
    : No device identifying information was found on the device. Device fingerprint data (canvas fingerprint) was not calculated.
device.match.reason.code
Describes how IA was able to determine the identity of the device. Only returned if VIP was able to identify the device. This field is not returned if the device engine is disabled in the IA policy, or if the
IAAuthData
field is not present in the request or is invalid.
  • EXACT_MATCH
    : IA identified a device that is registered to the user through the device identifier provided in the request. The device fingerprint data of the device matched the VIP data. IA determined that this device is registered to the user specified in the request.
  • CHANGES_UNDER_THRESHOLD
    : IA identified a device that is registered to the user through the device identifier provided in the request. The device fingerprint data of the device did not exactly match the VIP data, but the level of changes were below the threshold to invalidate the device. IA determined that this device is registered to the user specified in the request.
    • If the canvas fingerprint components have not changed, then the existing fingerprint record is updated to match the new value.
    • If the canvas fingerprint components have changed, then a new fingerprint record is stored and linked to the device. IA can make future canvas-based matches using any stored fingerprint for the device. Stored fingerprint records linked to the device are overwritten on a least-recently used basis.
  • CHANGES_ABOVE_THRESHOLD
    : IA identified a device that is registered to the user through the device identifier provided in the request. The device fingerprint data of the device did not exactly match the VIP data, and the level of changes were above the threshold to invalidate the device. IA could not verify that this device is registered to the user specified in the request.
  • SHARED_DEVICE
    : IA matched a registered device for another user from the same organization. IA could not verify that this device is registered to the user specified in the request.
device.fingerprint.changes
Indicates the device changes that IA identified. Only returned if device changes are found in a registered device. This field is not returned if the device engine is disabled in the IA policy, or if the
IAAuthData
field is not present or invalid in the request. Fingerprints with invalid components may only return a subset of the actual changes.
The value string is an array of JSON objects, with each object representing a detected change to the fingerprint of a registered device. Each change returns the following values:
  • component
    : The device attribute that has changed. The component can be one of the following:
    • Operating System
      : The name of the operating system used by the device
    • Operating System Version
      : The version number of the operating system used by the device
    • Browser Type
      : The classification of the browser used in the transaction (such as Chrome, Firefox)
    • Browser Version
      : The version number of the browser used in the transaction
    • Browser Plugins
      : A list of plugins and extensions that are detected as in use for the browser.
    • Screen Resolution
      : The available screen resolutions for the user device. Available resolutions are separated by the "|" symbol. The max-color-bit-depth is listed first.
    • Language
      : The default language dialect used by the client
    • Graphics Fingerprint
      : The rendering of some graphical images by the device has changed, or the rendering capabilities of the device has changed
    • Audio
      : The audio capabilities of the device
    • Video
      : The video capabilities of the device
    • Fonts
      : The font capabilities of the device
  • from
    : The fingerprint component value previously recorded for the device
  • to
    : The fingerprint component value currently returned for the device
device.fingerprint.details
Includes the uncompressed details of all fingerprint data from the request. Only returned if device changes are found in a registered device and the request included a value of
true
for the
IncludeFingerprintDetails
field. This field is not returned if the device engine is disabled in the IA policy, or if the
IAAuthData
field is not present or invalid in the request.
The value string is an array of JSON objects, with each object representing a fingerprint field value recorded as part of the fingerprint for a registered device. Each change returns the following values:
Not all values are returned for all requests.
  • fptg
    : A masked version of the unique tag identifier used to identify the device.
  • fpdt
    : Device type. Values may be
    browser
    (if the fingerprint was generated by JavaScript in a browser) or
    mobile client
    (if the fingerprint was generated by an API to the VIP mobile SDK).
  • fpcp
    : An encoding of the capabilities of the browser (for example, cookies are enabled, or support for various HTML 5 features).
  • fpln
    : The primary language encoding requested by the browser.
  • fptz
    : The time zone currently in use on the client.
  • fpsw
    : Installed software detected on the machine.
  • fppi
    : Browser extensions and plugins detected.
  • fpsc
    : Display attributes, such as screen resolution and depth.
  • fpua
    : User agent string used to identify the client type and version.
  • fpau
    : Audio capabilities of the device.
  • fpvd
    : Video capabilities of the device.
  • fpfn
    : List of installed fonts matched against a predefined list.
  • gfxfp:
    • cnvfp
      : A hash of a 2D image rendered on the device.
    • wglfp
      : A hash of a 3D image rendered on the device.
    • wglext
      : A hash of the capabilities data for the graphics device.
    • wglvr
      : A hash of WebGL version info (such as the graphics card provider and driver version).
  • gfxfp-verbose:
    • cnvfp
      : Supplemental information on a 2D image rendered on the device.
    • wglfp
      : Supplemental information on a 3D image rendered on the device.
    • wglext
      : Supplemental information on the capabilities data for the graphics device.
    • wglvr
      : Supplemental information on WebGL version info.