Skip to main content
ALTCHA®

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.

FieldTypeDescription
actionstringRequired. allow, deny, accept or set. See Actions.
conditionsarrayOptional, default []. At most 20 condition objects. A rule without conditions always matches.
conditionsOperatorstringOptional, default and. and: all conditions must hold; or: any condition must hold.
messagestringOptional. allow and deny only; at most 200 characters. Returned as error when this rule denies the request.
monitorbooleanOptional, default false. Evaluate the rule without effect. See Monitor mode.
namestringOptional. 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>.
setarrayset only, and required there: 1 to 10 set entries, each field at most once per rule.

Condition object

FieldTypeDescription
fieldstringRequired. One of the condition fields.
operatorstringRequired. One of the operators.
valuearray of stringsRequired. 1 to 100 values (comparison operators: exactly 1). Each value is trimmed and must then be 1 to 500 characters.

Set entry

FieldTypeDescription
fieldstringRequired. One of the set fields.
valuestringRequired. 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.

ActionWhen it matchesWhen it doesn't matchmessageset
allowContinue with the next rule.Deny the request.AllowedNot allowed
denyDeny the request.Continue.AllowedNot allowed
acceptAllow the request; later rules aren't evaluated.Continue.Not allowedNot allowed
setApply its entries, then continue.Continue.Not allowedRequired
  • End of list. After the last rule, the request is allowed. An empty rule list allows everything with default settings.
  • Settings accumulate. Later set rules overwrite values from earlier ones. Settings are those accumulated until evaluation stopped, so set rules after a deciding deny or accept don't apply.
  • Denial. A denied request gets 403 ACCESS_DENIED (see Errors). error is the deciding rule's message, or Denied by access rules (rule N). without one:
{ "code": "ACCESS_DENIED", "error": "Origin not allowed.", "statusCode": 403 }
  • After an allow. penalty.add is applied to the client's penalty, then rateLimit.limits is 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.

ActionA monitored rule fires whenInstead of
allowits conditions don't holddenying
denyits conditions holddenying
acceptits conditions holdallowing and stopping (later rules still run)
setits conditions holdapplying 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

ConstructSemantics
Several conditionsJoined by conditionsOperator: and (default) or or. No nesting; split complex logic across rules.
Several values in one conditionWith =, 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 valueWhen 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.
RangesCombine two comparisons with and, e.g. penalty >= 2 and penalty < 6.

Operators

OperatorMeaningFieldsValues
=matches any valueall1–100
!=matches no valueall1–100
>greater thanpenalty, riskexactly 1
>=greater than or equalpenalty, riskexactly 1
<less thanpenalty, riskexactly 1
<=less than or equalpenalty, riskexactly 1

Comparison operators on any other field fail validation with '>' is only valid on numeric fields (penalty, risk).

Condition fields

FieldMatches againstValuesMatchingExample
agentThe 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"]
countryThe 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"]
headersRequest 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"]
ipThe 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"]
languageEach Accept-Language tag, without ;q= weights; * tags are ignored.Language tags.Wildcard.["en", "de-*"]
methodThe HTTP method.Method names.Wildcard.["POST"]
networkThe 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"]
originOrigin (unless absent, unparseable or null), else Referer, reduced to scheme://authority.Origins.Wildcard.["https://example.com", "https://*.example.com"]
pathThe request path, without the query string.Paths.Wildcard.["/v2/verify"]
penaltyThe 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 >=
riskGET /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 >=
signalClassifier 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"]
threatThe 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"]
threatVerdictThe 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.

SyntaxMeaningExample
*Any sequence of characters, including none./v2/*
?Makes the preceding character optional.colou?r matches color and colour
\xLiteral 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

FieldValuesDefaultDescription
rateLimit.limitsComma-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.scopeapiKey, account (case-sensitive)apiKeyBuckets per API key or shared by all API keys of the account. Also buckets the /v2/classifier body's rateLimit.

Proof-of-work

FieldValuesDefaultDescription
pow.algorithmPBKDF2/SHA-256, PBKDF2/SHA-384, PBKDF2/SHA-512, SHA-256, SHA-384, SHA-512, ARGON2ID, SCRYPT (case-insensitive)PBKDF2/SHA-256Challenge algorithm. ARGON2ID and SCRYPT are memory-hard; widgets need their separately imported solvers.
pow.costInteger; 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.memoryCostInteger KiB, 1024 to [pow] max_memory_cost (default 262144).65536ARGON2ID memory. Other algorithms ignore it.
pow.counterN 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.expiresDuration from 10s to 24h, e.g. 20m.20mChallenge 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

FieldValuesDefaultDescription
classifier.aitrue, falsefalseTurns 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.aiInstructionsText, at most 1000 characters after trimming; empty = none.—What to reject. Enables AI_CUSTOM.
classifier.aiPurposeText, at most 1000 characters after trimming; empty = none.—What the form is for. Enables AI_OFF_TOPIC.
classifier.aiSignalsList of country, network, device, languages, timeZone, threats, emailDomain, rules (case-insensitive); empty = none.country network device languages timeZoneDetected signals sent to the AI provider with the text. The IP, full email address and payload are never sent.
classifier.disableRulesList 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.enableRulesList 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.fieldstrue, false— (challenge's ?fields=)Overrides serverVerificationFields: whether the widget sends its form fields to /v2/verify.
classifier.highRiskCountriesISO 3166-1 alpha-2 codes and lists high_risk, eu (case-insensitive); empty = none.high_riskA 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.similarityGroupsUp 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.trustedAppsUp to 20 app names (ASCII letters, digits, -_.+, at most 64 characters); empty = none.altcha-app altcha-rn altcha-flutterA 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

FieldValuesDefaultDescription
headerEntropy.limitN/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.penaltyNumber 0–10, at most one decimal.1Added to the client's penalty for each new distinct header hash beyond the first; 0 turns it off.

Human Interaction Signature

FieldValuesDefaultDescription
his.blockThresholdNumber 0.1–1, at most two decimals.0.8HIS 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.codeChallengetrue, falsefalseWith 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.hashTtlDuration from 10m to 7d, e.g. 12h.12hHow long a signature hash is remembered for replay detection.
his.modeoff, monitor, relaxed, strict (case-insensitive)offTurns on HIS scoring of POST /v2/challenge. While not off, GET /v2/challenge doesn't count against rateLimit.limits.
his.penaltyNumber 0–10, at most one decimal.1Added 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

FieldValuesDefaultDescription
penalty.addNumber -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

FieldValuesDefaultDescription
codeChallenge.alphabet2–36 ASCII letters or digits, at least 2 distinct (case-insensitive, duplicates ignored).234579Characters of the code.
codeChallenge.audiotrue, falsetruefalse drops the audio from the challenge; GET /v2/challenge/audio/<token>.wav then answers 404.
codeChallenge.audioLanguagesVoice language codes (see Languages), case-insensitive, separated by ,, ; or whitespace; unknown codes are rejected. Empty: every voice.Every voiceVoices 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.enabledtrue, falsefalseAdds 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.imageDifficultylow, standard, high (case-insensitive)standardImage style; high draws more and larger noise dots.
codeChallenge.lengthN or MIN-MAX, within 4–8.5Code length; a range picks a random length.

See Code challenge.

Limits

ItemLimit
Rules per security group100
Conditions per rule20
Values per condition1–100 (comparison operators: 1)
Characters per condition value (trimmed)1–500
Set entries per set rule1–10, no duplicate fields
name100 characters
message200 characters
classifier.aiPurpose, classifier.aiInstructions1000 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].

PathMessage
rulesat most 100 rules
rules[i].nameat most 100 characters; must not contain ',' or start with '#'
rules[i].messageat most 200 characters; only allow and deny rules have a message
rules[i].seta set rule needs 1 to 10 entries; only set rules have set entries
rules[i].set[k].fieldduplicate set field '…'
rules[i].set[k].valueThe 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].conditionsat most 20 conditions
rules[i].conditions[j].operator'…' is only valid on numeric fields (penalty, risk)
rules[i].conditions[j].value1 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"] }]
  }
]

Start typing to search...

↑ ↓ Navigate ↵ Select