Skip to main content
ALTCHA®

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:

  1. The widget calls GET /v2/challenge?apiKey=key_…. Instead of a challenge, Sentinel answers {"his": {"url": "/v2/challenge"}}. This GET isn't logged, isn't counted against rateLimit.limits, and isn't checked for header entropy.
  2. The widget posts its samples to POST /v2/challenge with the same query string (apiKey, params.*, fields). Sentinel scores them, checks them for tampering and replay, and either returns the challenge or 403 HIS_BLOCKED. Rule rate limits, header entropy and request logging apply to this POST.
  3. The issued challenge carries the score in its signed data. POST /v2/verify signs it into verificationData as his.automation, his.mode, his.assistive and his.flags, and outside monitor mode 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.modeEffect
off (default)GET /v2/challenge returns the challenge. A POST /v2/challenge body is ignored.
monitorScores the data and signs the score into the challenge. Never blocks, adds no penalty, and the HIS rules don't classify.
relaxedAdds 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.
strictBlocks 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" }
  ]
}
FieldDefaultDescription
his.modeoffoff, monitor, relaxed or strict (case-insensitive).
his.blockThreshold0.8Score (0.1–1, at most two decimals) at or above which the client is treated as a bot.
his.hashTtl12hHow long a signature is remembered for replay detection, 10m to 7d.
his.penalty1Added 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.

RuleMeaning
HIS_AUTOMATIONThe bot probability is above 0.5.
HIS_INTEGRITYThe samples are inconsistent: fabricated or tampered.
HIS_NO_INTERACTIONThe visitor neither moved, touched, scrolled, clicked nor typed.
HIS_REPLAYThe 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):

VisitorsBlocked
Real people0%
Simple automation scripts97%
AI agents using a browser95%
Scripts built to imitate people3%
  • 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 above 0.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.blockThresholdImitating bots blockedReal people blocked
0.8 (default)3%0%
0.620%0%
0.543%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.automation in verificationData, or hisAutomation in request logs), then switch to relaxed or strict.
  • relaxed before strict. relaxed turns a high score or a replay into penalty instead of a block, so a penalty condition can escalate repeat offenders, for example to a code challenge.
  • Lower his.blockThreshold carefully. 0.6 catches 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 hit HIS_BLOCKED, raise his.blockThreshold or switch to relaxed.

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 relaxed and strict. Use a separate security group for them.
  • Turning off the widget's humanInteractionSignature option 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.

Start typing to search...

↑ ↓ Navigate ↵ Select