Human Interaction Signature
Human Interaction Signature (HIS) scores how the visitor interacted with the page before solving the challenge, to tell people from automation. The widget collects pointer, touch, scroll, click, key and focus samples, and Sentinel turns them into a bot probability that it signs into the challenge and can block on.
How it works
HIS is off until a security-group set rule sets his.mode. With HIS on, the widget makes one extra round trip:
- The widget calls
GET /v2/challenge?apiKey=key_…. Instead of a challenge, Sentinel answers{"his": {"url": "/v2/challenge"}}. ThisGETisn't logged, isn't counted againstrateLimit.limits, and isn't checked for header entropy. - The widget posts its samples to
POST /v2/challengewith the same query string (apiKey,params.*,fields). Sentinel scores them, checks them for tampering and replay, and either returns the challenge or403 HIS_BLOCKED. Rule rate limits, header entropy and request logging apply to thisPOST. - The issued challenge carries the score in its signed data.
POST /v2/verifysigns it intoverificationDataashis.automation,his.mode,his.assistiveandhis.flags, and outsidemonitormode classifies it with the HIS rules.
Widget 3.0.0 and later collects HIS data; the click, key and untrusted data (HIS v2) need widget 3.6.0 or later. The widget side is described in Widget integration.
The score
The score is a bot probability from 0.01 to 1; higher means more bot-like. Sentinel scores each kind of interaction (pointer, touch, click, key, scroll and focus) on its own and combines them, taking into account whether the visitor is on a desktop or a touch device. Kinds of interaction without enough data are left out.
Keyboard-only or assistive-technology interaction is labeled assistive. The label doesn't change the score.
Integrity checks
Sentinel checks that the samples could have come from the widget. Data that looks fabricated or tampered with gets the INTEGRITY flag and scores as a bot, as does a browser that reports it is automated.
Replay detection
Sentinel remembers a hash of every signature per account, for his.hashTtl multiplied by the score: at least 10 minutes, at most his.hashTtl. Positions and timestamps enter the hash relative to the previous sample, so the same data shifted on screen or in time is still a replay. This catches replays with noise added or samples dropped.
The widget resends everything it has collected since page load with every POST /v2/challenge, so a retry overlaps earlier data. A match from the same client IP with exactly the same samples isn't a replay until it has been seen more than 5 times. A visitor whose IP changes between retries gets REPLAY.
Modes
his.mode | Effect |
|---|---|
off (default) | GET /v2/challenge returns the challenge. A POST /v2/challenge body is ignored. |
monitor | Scores the data and signs the score into the challenge. Never blocks, adds no penalty, and the HIS rules don't classify. |
relaxed | Adds his.penalty to the client's penalty for a score at or above his.blockThreshold or a replayed signature, but issues the challenge. Blocks a signature seen more than twice from a client whose penalty is 4 or more, and a request without HIS data. |
strict | Blocks a score at or above his.blockThreshold, a replayed signature, and a request without HIS data. |
A blocked request gets 403 HIS_BLOCKED without the reason, and adds his.penalty to the client's penalty.
Enabling it
HIS needs no server configuration. Turn it on with a set rule in the widget's security group:
{
"name": "his",
"action": "set",
"set": [
{ "field": "his.mode", "value": "relaxed" },
{ "field": "his.blockThreshold", "value": "0.8" },
{ "field": "his.hashTtl", "value": "12h" },
{ "field": "his.penalty", "value": "1" }
]
}| Field | Default | Description |
|---|---|---|
his.mode | off | off, monitor, relaxed or strict (case-insensitive). |
his.blockThreshold | 0.8 | Score (0.1–1, at most two decimals) at or above which the client is treated as a bot. |
his.hashTtl | 12h | How long a signature is remembered for replay detection, 10m to 7d. |
his.penalty | 1 | Added to the client's penalty on a block or a relaxed penalty (0–10, at most one decimal); 0 turns it off. |
his.codeChallenge also collects HIS data while a code challenge is entered and scores it at POST /v2/verify. Only widgets 3.6.0 and later send that data; older widgets are blocked in relaxed and strict, so keep it false until all your widgets are updated. All fields are in the Rules reference.
Rules & signals
POST /v2/verify classifies the signed assessment with four rules, outside monitor mode. /v2/classifier has no HIS input.
| Rule | Meaning |
|---|---|
HIS_AUTOMATION | The bot probability is above 0.5. |
HIS_INTEGRITY | The samples are inconsistent: fabricated or tampered. |
HIS_NO_INTERACTION | The visitor neither moved, touched, scrolled, clicked nor typed. |
HIS_REPLAY | The same signature was already submitted. |
The flags INTEGRITY, NO_INTERACTION and REPLAY are signed as his.flags. Scores and floors are in Classifier rules & scores. With requestLogging, the POST /v2/challenge is logged with hisAutomation and hisAssistive.
Using the API
The widget does this for you. To see the flow, post samples the way the widget does:
curl -X POST 'https://sentinel.example.com/v2/challenge?apiKey=key_…' \
-H 'Content-Type: application/json' \
-d '{"his": {"pointer": [[207, 302, 168], …], "click": [[480, 420, 3192, 95, 12, 8, 0, 14]], "key": [[3880, 102], …], "scroll": [[0, 50], …], "maxTouchPoints": 0, "v": 2, "webdriver": false}}'The challenge comes back unwrapped, with the score and mode in its signed data:
{
"configuration": { "verifyUrl": "/v2/verify", … },
"parameters": {
"algorithm": "PBKDF2/SHA-256",
"data": { "edk": "bd15…", "his": 0.44, "hisMode": "strict", "id": "375a…", "issued": 1795055941487 },
…
},
"signature": "d147…"
}hisFlags is added to data only when a flag is set, and assistive: true only for assistive interaction. Every field of his is optional and unknown fields are ignored. A tuple of the wrong length, more than 100 samples in one array, or a non-finite number returns 400 VALIDATION_ERROR.
The same body sent again from another client IP, or a body with "webdriver": true, is blocked in strict mode:
{ "code": "HIS_BLOCKED", "error": "Blocked by HIS.", "statusCode": 403 }See the POST /v2/challenge API reference and Error codes.
How well HIS works
We tested HIS against real visitors and a range of bots, from simple automation scripts to AI agents that drive a browser on their own and scripts built to imitate people. The results at the default his.blockThreshold (0.8):
| Visitors | Blocked |
|---|---|
| Real people | 0% |
| Simple automation scripts | 97% |
| AI agents using a browser | 95% |
| Scripts built to imitate people | 3% |
- No false positives. No real person was blocked, whether on a desktop or a phone, using a mouse, a trackpad, only the keyboard, the browser's autofill or a screen reader. Real people typically scored around
0.25, and none scored above0.5, well clear of the default threshold. - Automation is caught. Scripts and AI agents that fill in the form without behaving like a person are blocked almost every time.
- Bots that imitate people are the weak spot. They score higher than people, but mostly below the default threshold. Combine HIS with the other Sentinel features to slow them down (see Limitations).
The threshold trades bot detection against false positives:
his.blockThreshold | Imitating bots blocked | Real people blocked |
|---|---|---|
0.8 (default) | 3% | 0% |
0.6 | 20% | 0% |
0.5 | 43% | 1% |
Your visitors may score differently. Run HIS in monitor mode first to see your own score distribution before you block.
Tuning
- Start in
monitor. Check your visitors' scores (his.automationinverificationData, orhisAutomationin request logs), then switch torelaxedorstrict. relaxedbeforestrict.relaxedturns a high score or a replay into penalty instead of a block, so apenaltycondition can escalate repeat offenders, for example to a code challenge.- Lower
his.blockThresholdcarefully.0.6catches more imitating bots without blocking people in our test; below that, real visitors start to fail. - False positives. A visitor who neither moves, touches, scrolls, clicks nor types gets
NO_INTERACTION. If real users hitHIS_BLOCKED, raisehis.blockThresholdor switch torelaxed.
Limitations
- HIS can't prove that a visitor is human. An attacker who invests in imitating people can get past it. Combine it with proof-of-work, rate limits and header entropy, and the classifier.
- It needs the widget: backend calls send no HIS data and are blocked in
relaxedandstrict. Use a separate security group for them. - Turning off the widget's
humanInteractionSignatureoption breaks the widget when a rule turns HIS on. - Replay hashes are per account and live in the KV store; a signature replayed against another account isn't detected.