See api-docs Menu

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.

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/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 1.0 (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.

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

{
  "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://api.us.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"]
}'

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.