Home >
API >
2 >
Vigilance AI >
Get a Risk Score

Get a Risk Score

Use this API to get a real-time risk score for a user before completing a critical task or action.

For example, as part of an authentication flow you might check username/password and also obtain a risk score for the login. If the username/password is valid but the risk score is high you could step up to multi-factor authentication. Alternately if authentication is successful and the risk score is low then you could skip additional authentication.

The risk score is influenced by how much training data is supplied via the training API. As more event metadata is sent to the training API you can expect the risk scores returned to change.

Resource URL

https://api.<us_or_eu>.onelogin.com/api/2/risk/verify

Header Parameters

Authorization

required

string

Set to bearer:<access_token>.

Set <access_token> to the access token you generated using the Generate Token API.

The access token must have been generated using an API credential pair created using the scope required to call this API. This API can be called using any one of the following scopes: Authentication Only, Read Users, Manage users, Read All, or Manage All.

Content-Type

required

string

Set to application/json.

Request Parameters

required

string

The IP address of the User’s request.

user_agent

required

string

The user agent of the User’s request.

user

required

object

An Object containing User details.

The available object parameters are:

id - required A unique identifier for the user.
name - A name for the user.
authenticated - A boolean value which indicates if the metadata supplied in this event should be considered as trusted for the user. Defaults to false.

When using this API to get a risk score for user of the Adaptive Authentication service the user id must be in the following format.

{instance region}_{OneLogin User Id}

E.g. US_12345678

source

object

This field can used for targeting custom rules based on a group of people, customers, accounts, or even a single user.

The available object parameters are:

id - A unique id that represents the source of the event.
name - The name of the source

session

object

A dictionary of extra information that provides useful context about the session, for example the session ID, or some cookie information.

The available object parameters are:

id - If you use a database to track sessions, you can send us the session ID.

device

object

Information about the device being used.

The available object parameters are:

id - This device’s unique identifier

string

Set to the value of the __tdli_fp cookie.

Sample Request Body

{
  "ip" : "1.2.3.4",
  "user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3)...",
  "user" : {
    "id" : "112233",
    "name" : "Eve Smith"
  },
  "source" : {
    "id" : "1234",
    "name" : "ABC Inc"
  },
  "session" : {
    "id" : "xxxx-xxxxx-xxxxx-xxxxx"
  },
  "device" : {
    "id" : "xxx-xxx-xxx"
  }
}

Sample Response

200 OK
400 Bad Request
401 Unauthorized

{
    "score": 24,
    "triggers": [
        "Accessed from a new IP address",
        "Infrequent access from 125.238.248.246",
        "Infrequent access from Auckland, Auckland, New Zealand",
        "Infrequent access from New Zealand",
        "Infrequent access using Chrome on Macintosh",
        "Low trust for session"
    ],
    "messages": []
}

score

number

The risk score is a number between 0 and 1. Where 0 is low risk and 1 is the highest risk level possible.

risk_level

string

As our algorithm improves, the risk scores may change. For example, at one point in time a score greater than 0.5 might relate to an orange risk_level. Then later, it must be a score of 0.6 or more to get that orange status.

We recommend using the risk_level attribute in your app so that you aren’t coupled to the value of the score itself.

green - The event attributes are consistent with normal behavior for the user; there is a low risk their account is being impersonated.
orange - There are some aspects of the users behavior which are not normal; you may want to consider challenging the user with multi-factor authentication before proceeding.
red - The user is exhibiting very unusual behavior; you may want to deny them access or step up to multi-factor authentication.

triggers

array

Triggers are indicators of some of the key items that influenced the risk score. This is not an exhausative list of the reasons for the score and should only be used as a guide. We don’t recommend using the text of these triggers for decision making in your code.

Some examples of triggers are

“:browser on :platform is used infrequently”
“The IP :ip has been flagged as a threat in AlienVault Open Threat Exchange”
“:target_value is blacklisted”
“Device has not been seen before”
“Browser Cookie Expected”
“Machine learning processes indicated increased risk”
“:value is a new application”
“:value is a new location”
“:values has not been used before”
“Accessed from a new IP address”
“Accessed from a new browser session”
“The IP :ip has been blacklisted by projecthoneypot.org”
“:datetime (UTC/GMT) is an unusual time of day”
“Accessed from the Tor network”
“Infrequent access from :values”
“Infrequent access from :value”
“Infrequent access using :values”
“Infrequent access from :value”
“Low trust for session”
“Unexpectedly high velocity (:velocity km/hr)”

{
  messages: [
    "ip must not be blank",
    "user[id] must not be blank"
  ]
}

Invalid API Key

Sample Code

cURL

curl -XPOST 'https://api.us.onelogin.com/api/2/risk/verify' \
  -H 'Authorization: Bearer xxxxxxxxxxxxx' \
  -d '{
    "ip" : "1.2.3.4",
    "user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3)...",
    "user" : {
      "id" : "112233",
      "name" : "Eve Smith"
    }
}'

Postman Collection

Replace sample variables indicated by {{ }} with your actual values.

Download for the Vigilance API

Have a Question?

Have a how-to question? Seeing a weird error? Ask us about it on StackOverflow.

Found a bug? Submit a support ticket.

Have a product idea or request? Share it with us in our Ideas Portal.