See api-docs Menu
  1. Home >
  2. API >
  3. 2 >
  4. Vigilance AI >
  5. Create a Rule

Create a Rule

Create a custom rule to gain more control over the risk scoring of events.

For example, you can create a rule to blacklist certain countries or locations that will trigger a maximum risk score to be returned via the Verify API.

10 Minute Cache

Vigilance AI has a 10 minute cache for loading rules. This means that any rules that are created may not come into effect for up to 10 minutes.






Resource URL

https://<subdomain>/api/2/risk/rules

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: Manage All.

Content-Type

required

string

 Set to application/json.

Request Parameters

name

required

string

The name of this rule

type

required

string

The type parameter specifies the type of rule that will be created. Currently the following types are supported:

  • blacklist - If an event contains a value in a blacklist the risk score will always be 100 (HIGH).
  • whitelist - A white list value will override a blacklist with the same target parameter.

target

string

required

The target parameter that will be used when evaluating the rule against an incoming event. Currently the following targets are supported:

  • location.ip
  • location.address.country_iso_code

filters

string

required

An array of string values to evaluate against each event. It could be a list of IP addresses or country code or name.

IP Address

An IPv4 or IPv6 address or CIDR range. 

{
    "target": "location.ip",
    "filters": ["123.123.123.123", "192.168.2.1/24", "2001:db8::/32"]
}
If you want to blacklist every possible address you can create rule using IPv4 0.0.0.0/0 and IPv6 ::/0. You could then whitelist particular IPs or ranges.

Country Code

The ISO 3166 alpha-2 code for the country. 

{
    "target": "location.address.country_iso_code",
    "filters": ["NZ"]
}

source

string

The source can be used to scope rules to a specific group of people, customers, or even a single user. It matches against the source.id parameter that you can send with a Event or Verify API request.

e.g. You might want to blacklist certain IP addresses for a group of users. You could achieve this by creating a blacklist rule containing the IP address and setting the source to your own unique ID for the group that the user belongs to.

You can also use it to whitelist/override global blacklist rules. For example you create a blacklist on certain bad IP addresses and don’t specify source. Because one group needs access from a blacklisted IP you would create a whitelist rule containing that IP and the set the source to the group ID.

Source is not compatible with the OneLogin multi step login flow. It is for custom applications that make use of the Get a Risk Score API.

Sample Request Body

{
  "name": "IP Blacklist for Guests",
  "description": "Blacklist for guest account users",
  "type": "blacklist",
  "target": "location.ip",
  "source": "guest-123",
  "filters": ["123.123.123.123"]
}

Sample Response

  • 201 Created
  • 400 Bad Request
  • 401 Unauthorized
{
  "id": "816677874491720987",
  "name": "IP Blacklist for Guests",
  "description": "Blacklist for guest account users",
  "type": "blacklist",
  "target": "location.ip",
  "source": "guest-123",
  "filters": ["123.123.123.123"]
}

Invalid API Key

Sample Code

cURL

curl -XPOST 'https://<subdomain>.onelogin.com/api/2/risk/rules' \
  -H 'Authorization: Bearer xxxxxxxxxxxxx' \
  -d '{
    "name": "IP Blacklist for Guests",
    "description": "Blacklist for guest account users",
    "type": "blacklist",
    "target": "location.ip",
    "source": "guest-123",
    "filters": ["123.123.123.123"]
}'

Postman Collection

Replace sample variables indicated by {{ }} with your actual values.

Download for the Vigilance API

Run In Postman

    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.