Security Groups

The behavior of the Sentinel server is managed through Rules assigned to Security Groups.

Security rules are evaluated with every request made using an API key belonging to a Security Group. Rules enable you to allow or deny access based on specific conditions, as well as set internal state such as adjusting PoW complexity or enabling adaptive captcha.

API Keys

Autopilot

Configuring Security Rules requires advanced knowledge. Beginners are recommended to enable Autopilot, which manages rules automatically. Most customers won’t need to manually configure security groups.

Access Level

Each Security Group has an assigned Access Level that determines how the group and its API keys can be used:

Public: Allows access only to public-facing endpoints. Use this level with the ALTCHA widget.
Restricted: Permits access to non-administrative API endpoints. Recommended for external service integrations.
Full: Grants administrative access to all API endpoints, including data management.

Refer to the endpoint categorization below for details.

Endpoints

Public access level endpoints (accessible directly by end-users via ALTCHA Widget):

/v1/challenge
/v1/inspect
/v1/verify

Restricted access level endpoints (for server-side integrations and external services):

/v1/blobs/*
/v1/classifier
/v1/context/*
/v1/eml
/v1/ip
/v1/language
/v1/phishing
/v1/similarity
/v1/timezone

All other endpoints require Full access level.

Restricting by Request Origin

A common use of Security Group rules is to restrict access based on HTTP headers. Sentinel first checks the Origin header to determine the request’s origin. If the Origin header is missing, it attempts to retrieve the origin from the Referer header.

You can use the origin condition field in rules to explicitly allow or deny requests from specific origins. See the example below.

Restricting By Request Origin

Common use for Security Group Rules is restricion of access based on the HTTP headers. Sentinel detects the origin the from the Origin header, and if not provided, tries to retrive the origin from the Refer header. Rules provide condition field origin which can be used to allow or deny listed origins. See example below.

Examples

Allow Only Internal Traffic

To restrict access to specific IP addresses or networks, create an allow rule with an ip condition. This example permits access only from the 10.0.0.x range:

{
  "action": "allow",
  "conditions": [{
    "field": "ip",
    "operator": "=",
    "value": [
      "10.0.0.0/24"
    ]
  }],
  "name": "Allow internal traffic"
}

Apply IP restrictions only to restricted and full access groups. Public groups should remain accessible to all internet users.

Block High-Risk Countries

To reject requests from high-risk countries, add a deny rule with a country condition:

{
  "action": "deny",
  "conditions": [
    {
      "field": "country",
      "operator": "=",
      "value": [
        "list:high_risk"
      ]
    }
  ],
  "name": "Deny high-risk countries"
}

Block Bots and AI Agents

To reject automated requests from bots, crawlers, and AI agents:

{
  "action": "deny",
  "conditions": [
    {
      "field": "bot",
      "operator": "=",
      "value": [
        "true"
      ]
    }
  ],
  "name": "Deny bots"
}

Allow Only Specific Origin

{
  "action": "allow",
  "conditionsOperator": "or",
  "conditions": [
    {
      "field": "origin",
      "operator": "=",
      "value": [
        "https://example.com"
      ]
    },
    {
      "field": "origin",
      "operator": "=",
      "value": [
        "https://*.example.com"
      ]
    }
  ],
  "name": "Allow origins"
}

This example uses "conditionsOperator": "or" (introduced in version 1.12.0), which means that only one of the listed conditions must match instead of all of them. The second origin includes a wildcard * to match any subdomain.

Deny User-Agent from HTTP Headers

{
  "action": "deny",
  "conditions": [
    {
      "field": "headers",
      "operator": "=",
      "value": [
        "User-Agent: *bot/*"
      ]
    }
  ],
  "name": "Deny bot User-Agent"
}

This example demonstrates the use of the * wildcard - matches any string containing bot/.

Apply Penalty for TOR Network Usage

This rule increases the penalty score by 5 points for TOR network users. The penalty (0-10) affects adaptive measures like PoW complexity and captcha requirements.

Penalties >2 enforce code-challenge verification.

{
  "action": "set",
  "conditions": [
    {
      "field": "tor",
      "operator": "=",
      "value": [
        "true"
      ]
    }
  ],
  "name": "Set penalty to TOR users",
  "set": [
    {
      "field": "penalty",
      "value": "+5"
    }
  ]
}

Wildcards

Starting with version 1.12.0, Sentinel supports wildcards in rule conditions:

*: matches any sequence of characters
?: makes the previous character optional (applies to the single character immediately before the ?).

Examples:

https://*.example.com matches https://foo.example.com and https://bar.example.com.
colou?r matches color and colour (u is optional).
v?1 matches v1 and 1 (v is optional).

Schema

interface Rule {
  action: 'allow' | 'deny' | 'set'
  conditionsOperator?: 'and' | 'or'
  conditions: Condition[]
  name?: string
  set?: Set[]
}[]

interface Condition {
  field: ConditionField
  operator: Operator
  value: string[]
}

interface Set {
  field: SetField
  value: string
}

type SetField =
  | 'algorithm'
  | 'autopilot'
  | 'classifyFields'
  | 'codeChallenge'
  | 'complexity'
  | 'disableClassificationRules'
  | 'enableClassificationRules'
  | 'expires'
  | 'key'
  | 'penalty'
  | 'rateLimit'
  | 'threats'

type ConditionField =
  | 'bot'
  | 'country'
  | 'headers'
  | 'hosting'
  | 'ip'
  | 'language'
  | 'malicious'
  | 'mobile'
  | 'origin'
  | 'penalty'
  | 'proxy'
  | 'tor'

type Operator =
  | '='
  | '!='
  | '>'
  | '<'
  | '<='
  | '>='