Login Flow Guide

This guide explains how the Get a Risk Score and Track an Event APIs fit together in a login flow: when to call each one, and which verb to send at each step.

The two calls

  • Get a Risk Score (/api/2/risk/verify) asks “how risky does this login look right now?” It returns a score and the reasons for it. It never changes what Vigilance AI knows about the user.
  • Track an Event (/api/2/risk/events) tells Vigilance AI what actually happened. It returns an empty 200 response, not a score. When an event is trusted, Vigilance AI learns from it what is normal for the user, such as their usual IP addresses, locations and devices.

You use the score to decide what to do. You send events so that Vigilance AI can learn.

Trusted events

The user.authenticated flag on an event tells Vigilance AI whether to trust it. If you leave the flag out, a log-in event is trusted and every other verb is not.

A trusted event from a new IP address makes that address look normal on the next risk score. This is how a user who keeps logging in from the same place comes to have a low score. It also means that a trusted event must only describe a login you have fully accepted.

Never send a log-in event before MFA completes. If you send it when the password is accepted and the user then fails MFA, Vigilance AI has still learned that their IP address and location are normal. Each failed attempt from the same place then lowers the next score. Once the score drops under your MFA threshold, the next attempt is not challenged at all.

Set authenticated to true or false on every event, so the result never depends on the default.

If the password is wrong, send a log-in-denied event. Otherwise:

  1. Password accepted. Get a risk score. Don’t send a log-in event yet.
  2. Score at or below your threshold. Grant access, then send a log-in event.
  3. Score above your threshold. Challenge the user, for example with MFA, and send an authentication-challenge event.
  4. Challenge passed. Send an authentication-challenge-pass event, then a log-in event, and grant access.
  5. Challenge failed. Send only an authentication-challenge-fail event. Never send log-in for a failed attempt.

What each verb does today

  • log-in is trusted unless you say otherwise, so Vigilance AI learns from it.
  • authentication-challenge and authentication-challenge-pass are recorded but not trusted unless you say otherwise.
  • authentication-challenge-fail and log-in-denied are recorded, but they do not raise the user’s risk score. Repeated failures do not make the next score higher.
  • Get a Risk Score requests are never learned from.

User IDs

Use the same user id for a person in every call, both risk score requests and events.

If your users also log in through OneLogin, use the {instance region}_{OneLogin User Id} format, for example US_12345678. This is the format OneLogin uses for its own login events, so your calls and OneLogin’s describe the same user.

Worked example

A user enters the right password from an IP address they have never used before. Your MFA threshold is 20. Each request also needs the headers described on the Track an Event page.

1. Get a risk score with POST /api/2/risk/verify:

{
  "ip": "203.0.113.10",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
  "user": {
    "id": "US_12345678"
  }
}

The response:

{
  "score": 24,
  "triggers": [
    "Accessed from a new IP address",
    "Infrequent access from 203.0.113.10"
  ],
  "messages": []
}

2. The score is above 20, so challenge the user and send POST /api/2/risk/events:

{
  "verb": "authentication-challenge",
  "ip": "203.0.113.10",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
  "user": {
    "id": "US_12345678",
    "authenticated": false
  }
}

3. The user passes MFA. Send an authentication-challenge-pass event, which is the same as step 2 with "verb": "authentication-challenge-pass". Then send the log-in event and grant access:

{
  "verb": "log-in",
  "ip": "203.0.113.10",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
  "user": {
    "id": "US_12345678",
    "authenticated": true
  }
}

Vigilance AI now treats 203.0.113.10 as a known address for this user, so their next login from it will not be flagged as coming from a new IP address.

If the user had failed MFA instead, you would send only an authentication-challenge-fail event with "authenticated": false, and no log-in.