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.






Resource URL

https://<api-domain>/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.

device

object

Information about the device being used.

The available object parameters are:

  • id - This device’s unique identifier

fp

string

Set to the value of the __tdli_fp cookie.

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" : "US_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

Replace sample values indicated by < > with your actual values.

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" : "US_112233"
    }
}'

const request = require("request")

let options = {
  method: 'POST',
  uri: 'https://api.us.onelogin.com/auth/oauth2/v2/token',
  auth: {
    user: 'ONELOGIN CLIENT ID',
    pass: 'ONELOGIN CLIENT SECRET'
  },
  json: {
    grant_type: 'client_credentials'
  }
}

request(options, function(error, response, body){
  let accessToken = body.access_token
})
      

This example uses Dotnet Core 2.0


using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

.....

public async Task<string> GetAccessToken()
{
    var client = new HttpClient();

    var credentials = string.Format("{0}:{1}", "ONELOGIN CLIENT ID", "ONELOGIN CLIENT SECRET");

    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
        "Basic",
        Convert.ToBase64String(Encoding.UTF8.GetBytes(credentials))
    );

    var request = new HttpRequestMessage(){
        Method = HttpMethod.Post,
        RequestUri = new Uri("https://api.us.onelogin.com/auth/oauth2/v2/token"),
        Content = new StringContent("{ \"grant_type\": \"client_credentials\" }")
    };

    // We add the Content-Type Header like this because otherwise dotnet
    // adds the utf-8 charset extension to it which is not compatible with OneLogin
    request.Content.Headers.ContentType = new MediaTypeHeaderValue("application/json");

    var response = await client.SendAsync(request);
    var responseBody = await response.Content.ReadAsStringAsync();

    dynamic json = JsonConvert.DeserializeObject(responseBody);

    return json.access_token;
}
      

require 'httparty'

response = HTTParty.post('https://api.us.onelogin.com/auth/oauth2/v2/token',
  basic_auth: {
    username: 'ONELOGIN CLIENT ID',
    password: 'ONELOGIN CLIENT SECRET'
  },
  body: { grant_type: 'client_credentials' }.to_json,
  headers: {
    'content-type' => 'application/json'
  }
)

puts response['access_token']
      

import requests

r = requests.post('https://api.us.onelogin.com/auth/oauth2/v2/token',
  auth=('ONELOGIN CLIENT ID','ONELOGIN CLIENT SECRET'),
  json={
    "grant_type": "client_credentials"
  }
)
response = r.json()

print(response['access_token'])
      

CloseableHttpClient client = HttpClientBuilder.create().build();

HttpPost request = new HttpPost("https://api.us.onelogin.com/auth/oauth2/v2/token");

String credentials = String.format("%s:%s", "ONELOGIN CLIENT ID" , "ONELOGIN CLIENT SECRET");
byte[] encodedAuth = Base64.getEncoder().encode(credentials.getBytes());
String authHeader = "Basic " + new String(encodedAuth);

request.setHeader("Authorization", authHeader);
request.addHeader("Content-Type", "application/json");
request.setEntity(new StringEntity("{ \"grant_type\": \"client_credentials\" }", "UTF-8"));

try {
  CloseableHttpResponse reponse = client.execute(request);

  String content = EntityUtils.toString(reponse.getEntity());

  JSONObject json = new JSONObject(content);

  String accessToken = json.getString("access_token");

  System.out.println(accessToken);

} catch (IOException e) {
    e.printStackTrace();
}
      

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" : "US_112233"
    }
}'

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.