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://<subdomain>/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 100. Where 0 is low risk and 100 is the highest risk level possible. |
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://<subdomain>.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
- Clicking Run in Postman button navigates to the page where you can fork the collection to your workspace. Forking the collection into your workspace will enable you to contribute to the source collection using pull requests. You can also view the collection in a public workspace if you like and even import a copy of the collection using the links present on the screen.
Have a Question?
Found a problem or a bug? Submit a support ticket.
Looking for walkthroughs or how-to guides on OneLogin's user and admin features? Check out the documentation in our Knowledge Base.
Have a product idea or request? Share it with us in our Ideas Portal.