See api-docs Menu

Track an Event

Use this API to train Vigilance AI and help it improve the accuracy of contextual risk scores.

For example you can send user, browser, and device information when a successful login event has occurred. Vigilance AI will build up a profile of typical behavior for this type event for each user.

Early Preview Release

This API is currently in early preview release and may be subject to future breaking changes. If you’re interested in using this API please contact your account manager or our support team.

Resource URL

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

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

verb

required

string

Verbs are used to distinguish between different types of events.

Where possible use one of the following verbs to describe the event. Alternately you can create custom verbs to describe other types of actions within your application.

  • log-in - A user successfully logged into your app
  • log-out - The user has logged out
  • log-in-denied - The user failed to authenticate
  • authentication-challenge - Authentication was challenged (e.g. MFA was required)
  • authentication-challenge-pass - The authentication challenge was passed
  • authentication-challenge-fail - The authentication challenge failed

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:

  • 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 track additional events for the OneLogin 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.
  • td_cookie_id - When using our Javascript tracking library, a cookie is created. The cookie’s ID should be sent using this reserved key name.
  • td_cookie_expected - Send true when using our optional Javascript tracking library, and we’ll know to expect a cookie.

device

object

Information about the device being used.

The available object parameters are:

  • id - This device’s unique identifier

published

string

Date and time of the event in IS08601 format. Useful for preloading old events.

Defaults to date time this API request is received.

Sample Request Body

{
  "ip" : "1.2.3.4",
  "verb" : "log-in",
  "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

No content is returned. This API is fire and forget.

Invalid API Key

Sample Code

cURL

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

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.