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.

Related

• 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/classifier
• /v1/ip
• /v1/language
• /v1/similarity
• /v1/timezone

All other endpoints require Full access level.

Defining Rules

• Rules are evaluated top-to-bottom; evaluation stops when any rule denies access.
• An allow rule denies access if any condition fails.
• A deny rule denies access if all conditions are met.
• Conditions with multiple values are satisfied if at least one value meets the condition.

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"
}

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"
    }
  ]
}

Schema

interface Rule {
  action: 'allow' | 'deny' | 'set'
  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'

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

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