# Human Interaction Signature

> **Sentinel v2 (beta):** This page documents Sentinel v2, a beta rewrite that may change before the stable release. It does not apply to Sentinel v1, the current stable version: see the [Sentinel v1 documentation](/docs/sentinel.md).

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](#rules--signals).

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](/docs/sentinel/v2/integrate/widget/#human-interaction-signature-in-the-widget).

### 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](/docs/sentinel/v2/concepts/scoring/#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.

<Callout type="note" title="Changed in v2">

HIS scores aren't comparable with v1. The groups, weights and integrity rules changed, and `his.score` in `verificationData` is now the sum of the HIS rules, with the probability in `his.automation`. Re-check any `his.blockThreshold` you carried over. See [Breaking changes](/docs/sentinel/v2/upgrade/breaking-changes/#human-interaction-signature).

## Enabling it

HIS needs no server configuration. Turn it on with a `set` rule in the widget's security group:

```json
{
"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](/docs/sentinel/v2/features/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](/docs/sentinel/v2/reference/rules/#human-interaction-signature).

## 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](/docs/sentinel/v2/reference/classifier-rules/#human-interaction-signature). 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:

```bash
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`:

```json
{
"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:

```json
{ "code": "HIS_BLOCKED", "error": "Blocked by HIS.", "statusCode": 403 }
```

See the [`POST /v2/challenge` API reference](/sentinel-api-docs-v2.html#tag/challenge/POST/v2/challenge) and [Error codes](/docs/sentinel/v2/reference/errors/).

## 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 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](#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.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](/docs/sentinel/v2/reference/rules/#condition-fields) 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](/docs/sentinel/v2/features/proof-of-work/), [rate limits and header entropy](/docs/sentinel/v2/features/rate-limiting/), and the [classifier](/docs/sentinel/v2/features/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.

## Related

- [Widget integration](/docs/sentinel/v2/integrate/widget/#human-interaction-signature-in-the-widget)
- [Verifying submissions](/docs/sentinel/v2/integrate/verification/)
- [Rules reference: Human Interaction Signature](/docs/sentinel/v2/reference/rules/#human-interaction-signature)
- [Classifier rules & scores](/docs/sentinel/v2/reference/classifier-rules/#human-interaction-signature)
- [Scores, risk & penalty](/docs/sentinel/v2/concepts/scoring/)
- [Code challenge](/docs/sentinel/v2/features/code-challenge/)
- [Rate limiting & penalty](/docs/sentinel/v2/features/rate-limiting/)
