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-domain>/api/2/risk/verify
Header Parameters
Authorization required string | Set to Set 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: |
Content-Type required string |
Set to application/json . |
Request Parameters
ip 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:
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:
|
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:
|
device object |
Information about the device being used. The available object parameters are:
|
fp 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.
|
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
|
{
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.