latestSwagger 2.02026-08-109450223.9 KB

94acb422c07d

Unwanted Access Rules

Create an Unwanted Access Rule

Creates a new Unwanted Access Rule associated with your account, an organization, or a specific identity.

Rule logic. Provide exactly one of country_code, vpn, ip_address, or logic:

Omit logic and supply country_code, vpn, or ip_address to create standard rules. Provide a single value to create one rule, or a comma-separated list to create one standard rule per value in a single request. All rules share the same scope, type, and schedule, and are created atomically. If any value fails validation (for example a duplicate rule already exists, or an ip_address value is not a valid address or CIDR range), no rules are created. Duplicate values in the list are ignored. Only the last created rule is returned in the response. ip_address rules must be expected.
Set logic as catchall (with category) to create a catchall rule that matches every value in the category. Catchalls must be unauthorized and may only be scoped to the account or an organization. An account or organization may have at most one catchall per category.
Set logic as catchall_exception (with category) to create an exception that opts an organization out of an account-level catchall. Exceptions must be expected, may only be scoped to an organization, and must omit starts_at/expires_at.

Scope. The rule scope is determined by the IDs supplied: provide identity_id to scope the rule to a single identity, organization_id to scope it to an organization. Omitting both scopes the rule at the account level.

post/v1/unwanted_access_rules

Request body

identity_idinteger

Scope the rule to a specific identity. Mutually exclusive with organization_id. If neither is provided, the rule is scoped to the account.

organization_idinteger

Scope the rule to an organization. Mutually exclusive with identity_id. If neither is provided, the rule is scoped to the account.

country_codestring

ISO 3166-1 alpha-2 country code(s) this rule should match. Provide for standard rules. Accepts a single code or a comma-separated list, which creates one rule per code. Mutually exclusive with vpn, ip_address, and logic.

vpnstring

Tunnel operator name(s) this rule should match. Provide for standard rules. Accepts a single name or a comma-separated list, which creates one rule per name. Mutually exclusive with country_code, ip_address, and logic.

ip_addressstring

IP address(es) or CIDR range(s) this rule should match. Provide for standard rules, which must be of type expected. Each value must be a valid IPv4 or IPv6 address or CIDR range. Accepts a single address or a comma-separated list, which creates one rule per address. Mutually exclusive with country_code, vpn, and logic.

logic'catchall' | 'catchall_exception'

Rule logic. Set to catchall to match every value in a category, or catchall_exception to opt an organization out of an account-level catchall. Omit to create a standard rule (in which case country_code, vpn, or ip_address is required). Mutually exclusive with country_code, vpn, and ip_address.

type'expected' | 'unauthorized' required

Whether matching access is expected or unauthorized. Must be unauthorized when rule logic is catchall and expected when rule logic is catchall_exception.

starts_atstring date

UTC date (YYYY-MM-DD) when the rule becomes active. Omit for expected rules that should start immediately. Must be omitted for unauthorized rules and for rules with logic of catchall or catchall_exception.

expires_atstring date

UTC date (YYYY-MM-DD) when the rule expires. Omit for expected rules that should never expire. Must be omitted for unauthorized rules and for rules with logic of catchall or catchall_exception.

notesstring

Optional free-text note to attach to the rule.

category'country' | 'vpn'

Category that the catchall or exception applies to. Required when logic is provided.

Response

Create an Unwanted Access Rule

Example response

{
  "unwanted_access_rule": {
    "id": 84938,
    "applied_to": {
      "type": "Organization",
      "id": 1234,
      "name": "ExampleCo"
    },
    "category": "country",
    "country_code": "US",
    "vpn": "NORD_VPN",
    "ip_address": "203.0.113.0/24",
    "type": "unauthorized",
    "status": "active",
    "logic": "standard",
    "note": "Approved by compliance — regional office access",
    "starts_at": "2025-09-05T18:20:34Z",
    "expires_at": "2025-12-05T18:20:34Z",
    "created_by": "Jane Doe",
    "created_at": "2025-09-05T18:20:34Z",
    "updated_at": "2025-09-05T18:20:34Z"
  }
}