Rules reference
The complete grammar for security-group rules: every field, action, condition, operator and set entry Sentinel accepts. For an introduction, see Security groups & rules.
A security group's rules is an ordered JSON array. Rules gate every API-key request (/v2/challenge, /v2/verify, /v2/inspect and API-key calls to the other endpoints). Rules are created and replaced through the security-group endpoints of the API reference; an update replaces the whole list.
Rule object
Unknown keys are rejected. Optional fields are omitted from stored rules when they have their default value.
| Field | Type | Description |
|---|---|---|
action | string | Required. allow, deny, accept or set. See Actions. |
conditions | array | Optional, default []. At most 20 condition objects. A rule without conditions always matches. |
conditionsOperator | string | Optional, default and. and: all conditions must hold; or: any condition must hold. |
message | string | Optional. allow and deny only; at most 200 characters. Returned as error when this rule denies the request. |
monitor | boolean | Optional, default false. Evaluate the rule without effect. See Monitor mode. |
name | string | Optional. At most 100 characters; must not contain , or start with #. Labels the rule in GET /v2/inspect and in request logs (context.rules, context.monitor), where unnamed rules appear as #<index>. |
set | array | set only, and required there: 1 to 10 set entries, each field at most once per rule. |
Condition object
| Field | Type | Description |
|---|---|---|
field | string | Required. One of the condition fields. |
operator | string | Required. One of the operators. |
value | array of strings | Required. 1 to 100 values (comparison operators: exactly 1). Each value is trimmed and must then be 1 to 500 characters. |
Set entry
| Field | Type | Description |
|---|---|---|
field | string | Required. One of the set fields. |
value | string | Required. Always a string, also for numbers and booleans ("true", "5000"). Leading and trailing whitespace is ignored. |
Naming convention
Presets name their rules preset:<id>:<part>, for example preset:recommended:base. A UI can detect an applied preset by its preset:<id>: prefix. See Presets.
Actions
Rules run in order. A rule matches when it has no conditions, or when all (and) or any (or) of its conditions hold.
| Action | When it matches | When it doesn't match | message | set |
|---|---|---|---|---|
allow | Continue with the next rule. | Deny the request. | Allowed | Not allowed |
deny | Deny the request. | Continue. | Allowed | Not allowed |
accept | Allow the request; later rules aren't evaluated. | Continue. | Not allowed | Not allowed |
set | Apply its entries, then continue. | Continue. | Not allowed | Required |
- End of list. After the last rule, the request is allowed. An empty rule list allows everything with default settings.
- Settings accumulate. Later
setrules overwrite values from earlier ones. Settings are those accumulated until evaluation stopped, sosetrules after a decidingdenyoracceptdon't apply. - Denial. A denied request gets
403 ACCESS_DENIED(see Errors).erroris the deciding rule'smessage, orDenied by access rules (rule N).without one:
{ "code": "ACCESS_DENIED", "error": "Origin not allowed.", "statusCode": 403 }- After an allow.
penalty.addis applied to the client's penalty, thenrateLimit.limitsis enforced. Denied requests add no penalty.
Monitor mode
A rule with "monitor": true is evaluated as written but has no effect: it never denies, allows or stops evaluation, and its set entries aren't applied. It is validated as if it were live, so clearing the flag always saves.
| Action | A monitored rule fires when | Instead of |
|---|---|---|
allow | its conditions don't hold | denying |
deny | its conditions hold | denying |
accept | its conditions hold | allowing and stopping (later rules still run) |
set | its conditions hold | applying its entries |
Fired monitored rules are listed in the request log's context.monitor (a monitored set without conditions fires on every request and isn't listed). Later rules see only live state: a monitored classifier.* entry doesn't change a later risk condition. Monitored threat and threatVerdict conditions still trigger the threat lookup.
Combining conditions
| Construct | Semantics |
|---|---|
| Several conditions | Joined by conditionsOperator: and (default) or or. No nesting; split complex logic across rules. |
| Several values in one condition | With =, the condition holds when the request value matches any value. |
| Negation | != is the exact negation of =: it holds when the request value matches none of the values. |
| Missing request value | When the request has no value (no Origin/Referer, no Accept-Language, unknown country, no network flags, unsigned request for agent), = is false and != is true. |
| Ranges | Combine two comparisons with and, e.g. penalty >= 2 and penalty < 6. |
Operators
| Operator | Meaning | Fields | Values |
|---|---|---|---|
= | matches any value | all | 1–100 |
!= | matches no value | all | 1–100 |
> | greater than | penalty, risk | exactly 1 |
>= | greater than or equal | penalty, risk | exactly 1 |
< | less than | penalty, risk | exactly 1 |
<= | less than or equal | penalty, risk | exactly 1 |
Comparison operators on any other field fail validation with '>' is only valid on numeric fields (penalty, risk).
Condition fields
| Field | Matches against | Values | Matching | Example |
|---|---|---|---|---|
agent | The request's Web Bot Auth signature. | verified, unverified, an agent name, or a kind: crawler, ai_training, ai_search, user_fetch. | Wildcard. A verified agent matches verified, its name and its kind; a signed request that fails verification matches unverified; unsigned requests match nothing, so * matches every signed request. | ["verified"] |
country | The client IP's country, from the [ip_resolver] providers. | ISO 3166-1 alpha-2 codes, high_risk, eu; one value may hold several separated by ,, ; or whitespace. | Case-insensitive, no wildcards. Unknown codes fail with unknown country code or list 'xx'. | ["high_risk", "us ca"] |
headers | Request headers. | Name: pattern, or a bare Name. | Header name case-insensitive. Matches when any value of the header matches the wildcard pattern; a bare name (or empty pattern) checks presence. Header values that aren't visible ASCII are skipped. | ["X-Client: mobile-*", "X-Debug"] |
ip | The client IP. | IP addresses or CIDR ranges (IPv4 or IPv6). | No wildcards. IPv4-mapped IPv6 clients match IPv4 ranges. | ["10.0.0.0/8", "2001:db8::/32"] |
language | Each Accept-Language tag, without ;q= weights; * tags are ignored. | Language tags. | Wildcard. | ["en", "de-*"] |
method | The HTTP method. | Method names. | Wildcard. | ["POST"] |
network | The client IP's network flags. | fixed (flags known, none set), mobile, hosting, proxy, tor. | Case-insensitive, no wildcards. Each flag matches on its own: a Tor exit in a data center matches both tor and hosting. | ["hosting", "proxy"] |
origin | Origin (unless absent, unparseable or null), else Referer, reduced to scheme://authority. | Origins. | Wildcard. | ["https://example.com", "https://*.example.com"] |
path | The request path, without the query string. | Paths. | Wildcard. | ["/v2/verify"] |
penalty | The client's penalty (0–10) from before this request. | Numbers 0–10 with at most one decimal. | Numeric; =/!= compare exactly. No wildcards or ranges. | ["4"] with >= |
risk | GET /v2/inspect's risk (0–10) without a time zone: device, IP and location rules (HIGH_RISK_COUNTRY of the IP's country), capped at 10. | Numbers 0–10 with at most one decimal. | As penalty. Computed with the classifier.* settings of set rules before this rule. | ["5"] with >= |
signal | Classifier rules scoring above 0 for the request. | Device rules ACCEPT_HEADER_MISSING, ACCEPT_LANGUAGE_HEADER_MISSING, BOT, CLI, LIBRARY, USER_AGENT_HEADER_MISSING, USER_AGENT_HEADER_UNCOMMON; IP rules BOT, HIGH_RISK_COUNTRY, HOSTING, MALICIOUS, PROXY, THREAT_SCORE, TOR. | Case-insensitive. All listed rules run regardless of classifier.enableRules/disableRules; classifier.trustedApps and classifier.highRiskCountries from earlier rules apply. Rules that need the /v2/verify body fail validation. | ["MALICIOUS", "TOR"] |
threat | The client IP's threat-list matches. | A source name (manual, auto, or a threat source's name) or a kind: bot, malicious, probe, proxy, tor, crawler, ai_training, ai_search, user_fetch. | Wildcard. Private IPs have no matches; other non-routable IPs match only manual entries. | ["tor", "malicious"] |
threatVerdict | The client IP's threat verdict. | allow, block, none. | Case-insensitive, no wildcards. none when no match decides (also for private IPs). The most specific entry with an action decides, otherwise any allow source, otherwise any block source. | ["block"] |
country, network, IP signals and risk resolve the client IP through the [ip_resolver] providers once per request, within 1 second; after a timeout only the threat data is known. See IP resolvers and Threat intelligence.
Wildcards
agent, headers patterns, language, method, origin, path and threat values are wildcard patterns, matched against the whole value, case-insensitively.
| Syntax | Meaning | Example |
|---|---|---|
* | Any sequence of characters, including none. | /v2/* |
? | Makes the preceding character optional. | colou?r matches color and colour |
\x | Literal x. | \*, \?, \\ |
A ? at the start of a pattern or after * fails with '?' must follow a character; a trailing \ fails with dangling '\'.
Set fields
Fields use feature.parameter notation. Values are strings. Defaults apply when no matching rule sets the field.
Rate limiting
| Field | Values | Default | Description |
|---|---|---|---|
rateLimit.limits | Comma-separated points/duration[(params)], e.g. 10/1m,100/1h(sliding&key=ip). | — (no limit) | Enforced on every API-key request after the rules allow it; the first exceeded limit answers 429 RATE_LIMITED (later limits aren't counted). Param key: edk (default; per device key: client IP, User-Agent, Accept-Language, rotated daily), ip (per client IP) or uid (one bucket per scope); case-insensitive, last key= wins. Other params follow [rate_limit] global. |
rateLimit.scope | apiKey, account (case-sensitive) | apiKey | Buckets per API key or shared by all API keys of the account. Also buckets the /v2/classifier body's rateLimit. |
Proof-of-work
| Field | Values | Default | Description |
|---|---|---|---|
pow.algorithm | PBKDF2/SHA-256, PBKDF2/SHA-384, PBKDF2/SHA-512, SHA-256, SHA-384, SHA-512, ARGON2ID, SCRYPT (case-insensitive) | PBKDF2/SHA-256 | Challenge algorithm. ARGON2ID and SCRYPT are memory-hard; widgets need their separately imported solvers. |
pow.cost | Integer; range depends on the algorithm (below). | 5000 (PBKDF2, SHA), 2 (ARGON2ID), 65536 (SCRYPT) | PBKDF2 iterations or SHA hash rounds: 1–1000000. ARGON2ID passes: 1–10. SCRYPT N: a power of 2 from 1024 to the largest power of 2 within [pow] max_memory_cost (block size 8, so N is also memory in KiB). |
pow.memoryCost | Integer KiB, 1024 to [pow] max_memory_cost (default 262144). | 65536 | ARGON2ID memory. Other algorithms ignore it. |
pow.counter | N or MIN-MAX, within 1–1000000. | 1-15000 (PBKDF2), 1-1000 (SHA), 1-200 (ARGON2ID, SCRYPT) | Solution counter; a range picks a random value per challenge. Start ranges at 1; see Proof-of-work. |
pow.expires | Duration from 10s to 24h, e.g. 20m. | 20m | Challenge lifetime. |
A pow.cost must fit every algorithm it can end up with when any subset of rules matches: the pow.algorithm of its own rule, or else of every earlier rule and the default; plus the algorithm of every later rule that doesn't set its own pow.cost. Set pow.algorithm and pow.cost in the same rule to avoid conflicts. Stored rules aren't rechecked if [pow] max_memory_cost changes; challenge issuing clamps costs to the algorithm's range.
Classifier
| Field | Values | Default | Description |
|---|---|---|---|
classifier.ai | true, false | false | Turns on the AI decider for /v2/verify, /v2/classifier and /v2/eml (needs a [classifier.ai] provider): AI_SPAM, AI_SCAM, AI_ABUSE, AI_GIBBERISH, plus AI_OFF_TOPIC and AI_CUSTOM below. |
classifier.aiInstructions | Text, at most 1000 characters after trimming; empty = none. | — | What to reject. Enables AI_CUSTOM. |
classifier.aiPurpose | Text, at most 1000 characters after trimming; empty = none. | — | What the form is for. Enables AI_OFF_TOPIC. |
classifier.aiSignals | List of country, network, device, languages, timeZone, threats, emailDomain, rules (case-insensitive); empty = none. | country network device languages timeZone | Detected signals sent to the AI provider with the text. The IP, full email address and payload are never sent. |
classifier.disableRules | List of classifier rule names (case-insensitive); empty = none. | — | Default for /v2/verify and /v2/classifier (a request body's disableRules replaces it). With a disable list, every rule but those runs. |
classifier.enableRules | List of classifier rule names; empty = none. | — | Default for /v2/verify and /v2/classifier. Without a disable list, only the enabled rules run; with neither, all run. |
classifier.fields | true, false | — (challenge's ?fields=) | Overrides serverVerificationFields: whether the widget sends its form fields to /v2/verify. |
classifier.highRiskCountries | ISO 3166-1 alpha-2 codes and lists high_risk, eu (case-insensitive); empty = none. | high_risk | A location in one of them scores 2 on HIGH_RISK_COUNTRY. high_risk: by cd cf cu il iq ir kp lb ly mm ng ru sd so sy ua ve zw; eu: the 27 EU members. |
classifier.similarityGroups | Up to 50 training groups (a-z0-9_-, at most 64 characters, starting with a letter or digit), builtin:-prefixed groups, or * (case-insensitive); empty = none. | * | Groups SIMILARITY and NEAR_DUPLICATE compare text against. Unknown groups are skipped. |
classifier.trustedApps | Up to 20 app names (ASCII letters, digits, -_.+, at most 64 characters); empty = none. | altcha-app altcha-rn altcha-flutter | A User-Agent containing the product token name/version of one of them (case-insensitive) scores 0 on USER_AGENT_HEADER_UNCOMMON, CLI and LIBRARY. |
Lists are separated by ,, ; or whitespace.
Header entropy
| Field | Values | Default | Description |
|---|---|---|---|
headerEntropy.limit | N/DURATION, N 1–99, DURATION 1m to 24h, e.g. 10/4h. | — (off) | Distinct device header sets per client IP and rateLimit.scope on /v2/challenge and /v2/inspect, in a fixed window from the first one. More than N answer 429 HEADER_ENTROPY until the window ends. |
headerEntropy.penalty | Number 0–10, at most one decimal. | 1 | Added to the client's penalty for each new distinct header hash beyond the first; 0 turns it off. |
Human Interaction Signature
| Field | Values | Default | Description |
|---|---|---|---|
his.blockThreshold | Number 0.1–1, at most two decimals. | 0.8 | HIS score (higher means more bot-like) at or above which the client is treated as a bot: blocked in strict, penalized in relaxed, only logged in monitor. |
his.codeChallenge | true, false | false | With his.mode not off, a code challenge also collects HIS data while the code is entered and /v2/verify scores it. Widgets that don't send it are blocked in relaxed/strict. |
his.hashTtl | Duration from 10m to 7d, e.g. 12h. | 12h | How long a signature hash is remembered for replay detection. |
his.mode | off, monitor, relaxed, strict (case-insensitive) | off | Turns on HIS scoring of POST /v2/challenge. While not off, GET /v2/challenge doesn't count against rateLimit.limits. |
his.penalty | Number 0–10, at most one decimal. | 1 | Added to the client's penalty in relaxed and strict when HIS data is missing, replayed, or scores at or above his.blockThreshold; 0 turns it off. |
See Human Interaction Signature.
Penalty
| Field | Values | Default | Description |
|---|---|---|---|
penalty.add | Number -10 to 10, at most one decimal. | — | Added to the client's penalty (clamped to 0–10) when evaluation ends in allow, before rateLimit.limits. |
Code challenge
| Field | Values | Default | Description |
|---|---|---|---|
codeChallenge.alphabet | 2–36 ASCII letters or digits, at least 2 distinct (case-insensitive, duplicates ignored). | 234579 | Characters of the code. |
codeChallenge.audio | true, false | true | false drops the audio from the challenge; GET /v2/challenge/audio/<token>.wav then answers 404. |
codeChallenge.audioLanguages | Voice language codes (see Languages), case-insensitive, separated by ,, ; or whitespace; unknown codes are rejected. Empty: every voice. | Every voice | Voices the audio may use: the first language / Accept-Language candidate on the list, else the first listed voice that speaks the code (instead of en). No listed voice for the code: the challenge has no audio. |
codeChallenge.enabled | true, false | false | Adds a code challenge to /v2/challenge. /v2/verify requires the code (case-insensitive); a wrong or missing code answers INCORRECT_CODE and burns the challenge. |
codeChallenge.imageDifficulty | low, standard, high (case-insensitive) | standard | Image style; high draws more and larger noise dots. |
codeChallenge.length | N or MIN-MAX, within 4–8. | 5 | Code length; a range picks a random length. |
See Code challenge.
Limits
| Item | Limit |
|---|---|
| Rules per security group | 100 |
| Conditions per rule | 20 |
| Values per condition | 1–100 (comparison operators: 1) |
| Characters per condition value (trimmed) | 1–500 |
Set entries per set rule | 1–10, no duplicate fields |
name | 100 characters |
message | 200 characters |
classifier.aiPurpose, classifier.aiInstructions | 1000 characters |
Validation errors
Rules are validated on create and update. An invalid list returns 400 INVALID_RULES; error is path: message, with a path such as rules[2].conditions[0].value[1].
| Path | Message |
|---|---|
rules | at most 100 rules |
rules[i].name | at most 100 characters; must not contain ',' or start with '#' |
rules[i].message | at most 200 characters; only allow and deny rules have a message |
rules[i].set | a set rule needs 1 to 10 entries; only set rules have set entries |
rules[i].set[k].field | duplicate set field '…' |
rules[i].set[k].value | The field's range, e.g. must be a duration from 10s to 24h, e.g. '20m'; for pow.cost conflicts, the algorithm and a hint such as set pow.algorithm and pow.cost in the same rule. |
rules[i].conditions | at most 20 conditions |
rules[i].conditions[j].operator | '…' is only valid on numeric fields (penalty, risk) |
rules[i].conditions[j].value | 1 to 100 values; '…' takes exactly one value |
rules[i].conditions[j].value[k] | must be 1 to 500 characters; invalid IP or CIDR '…'; invalid header name '…'; unknown threat verdict '…' (use allow, block or none); unknown network '…' (use fixed, mobile, hosting, proxy or tor); '…' is not a signal (use …); must be a number from 0 to 10 with at most one decimal; wildcard syntax errors. |
Unknown keys, actions, fields and operators are rejected when the request body is parsed.
Examples
Restrict a public key to your origins, let your office through, and block threats:
[
{
"name": "office",
"action": "accept",
"conditions": [{ "field": "ip", "operator": "=", "value": ["203.0.113.0/24"] }]
},
{
"name": "origins",
"action": "allow",
"message": "Origin not allowed.",
"conditions": [
{ "field": "origin", "operator": "=", "value": ["https://example.com", "https://*.example.com"] }
]
},
{
"name": "threats",
"action": "deny",
"message": "Blocked by threat intelligence.",
"conditions": [
{ "field": "threatVerdict", "operator": "=", "value": ["block"] },
{ "field": "path", "operator": "!=", "value": ["/v2/verify"] }
]
}
]Base limits plus escalation by risk and penalty, with one rule in monitor mode:
[
{
"name": "base",
"action": "set",
"set": [
{ "field": "rateLimit.limits", "value": "50/10m" },
{ "field": "headerEntropy.limit", "value": "10/4h" }
]
},
{
"name": "elevated",
"action": "set",
"conditionsOperator": "or",
"conditions": [
{ "field": "risk", "operator": ">=", "value": ["4"] },
{ "field": "penalty", "operator": ">", "value": ["2"] },
{ "field": "signal", "operator": "=", "value": ["BOT", "CLI", "LIBRARY", "MALICIOUS", "PROXY", "TOR"] }
],
"set": [
{ "field": "codeChallenge.enabled", "value": "true" },
{ "field": "pow.counter", "value": "1-30000" }
]
},
{
"name": "memory-hard",
"action": "set",
"conditions": [{ "field": "risk", "operator": ">=", "value": ["7"] }],
"set": [
{ "field": "pow.algorithm", "value": "ARGON2ID" },
{ "field": "pow.cost", "value": "3" },
{ "field": "pow.memoryCost", "value": "65536" }
]
},
{
"name": "repeat-offenders",
"action": "deny",
"monitor": true,
"message": "Too many failed attempts.",
"conditions": [{ "field": "penalty", "operator": ">=", "value": ["8"] }]
}
]