Client‑Side Human Identification for Web¶

Human Identity by Wallarm is a client-side service that verifies whether requests to your applications come from real users or automated tools. It covers web and mobile platforms — this article describes the Web Antibot component.

Overview¶

Web Antibot is a JavaScript-based agent that detects and blocks automated behavior in browsers. It verifies the browser environment at the moment of a user action and provides a signed verdict (human, suspicious, or bot).

Depending on your setup, the verdict can be enforced by Wallarm's modules or by your own backend logic.

Where human identification adds value¶

Public web applications always receive automated traffic. Bots load content, execute JavaScript, and interact with pages like real users — clicking login, sign up, checkout, and other actions.

These actions are not harmless. Bots use them to:

• Attempt account takeover (credential stuffing)

• Create fake accounts at scale

• Abuse checkout and inventory

• Probe endpoints to prepare attacks, etc.

Even when they do not complete the flow, they still create problems: security risks, increased costs, and distorted analytics (e.g., fake clicks on critical actions).

Human Identity solves these problems by verifying the browser execution environment before the action is processed. It can be used anywhere in your application, but is most effective for high-value actions:

How it works¶

At a high level: a JavaScript library collects browser signals, the Human Identification Server (hosted and managed by Wallarm) evaluates them and returns a signed JWT with a verdict. The verdict is then enforced — either by Wallarm's modules or by your own backend logic.

Step-by-step flow¶

1. Load & collect signals
   Your page loads the engine.js library asynchronously. It initializes a WASM engine, loads application-specific bytecode, and starts collecting browser signals (environment, rendering, behavior) in the background.

2. Verify on user action
   When the user triggers a protected action (e.g., login), your code calls evaluate(). The library finalizes collection and sends the signals to the Human Identification Server (hosted and managed by Wallarm).

3. Analysis & decision
   The server runs detection checks, computes a risk score, and assigns a verdict: human, suspicious, or bot.

4. Token issuance
   The result is returned as a signed JWT containing the verdict, score, and a stable device identifier (hid).

5. Enforce
   How you enforce the verdict depends on your setup. If you use a Wallarm Node inline, store the JWT in a cookie and configure hid as a session context parameter in Wallarm Console — Wallarm's modules handle the rest.

   If you use your own backend, attach the JWT to the request and verify it server-side.

Library functions¶

The engine.js library provides 2 functions used in the flow above:

After evaluate() completes, the engine stops. For each new protected action, call start() and evaluate() again.

Each evaluate() call produces a new JWT (new iat, exp, potentially new score). If the user reloads the page, the entire cycle restarts: start() collects signals again, evaluate() returns a fresh token.

Token¶

The Human Identity service returns a signed JWT. The JWT contains the following claims:

Setup¶

Step 1: Get your credentials¶

Contact sales@wallarm.com to enable Human Identity. Provide the domain(s) where you plan to integrate the solution (e.g., login.example.com).

The Wallarm team will provision a server instance for your account and provide:

• Human Identification Server (HID) endpoint — the base URL depends on the chosen Wallarm Cloud region:

  • https://human-id.us-hi.wallarm.com/ for the US Cloud
  • https://human-id.eu-hi.wallarm.com/ for the EU Cloud

• Application ID — identifies your application in the HIS and links requests to your configuration.

You will use these credentials when initializing the Wallarm JavaScript library.

Step 2: Integrate the library and protect an action¶

Add the engine.js library to your page and wire it to the action you want to protect.

Below are 2 integration examples:

<form id="login-form" action="/login" method="POST">
    <input type="email" name="email" placeholder="Email" required>
    <input type="password" name="password" placeholder="Password" required>
    <input type="hidden" name="hid_token" id="hid-token">
    <button type="button" id="login-btn">Log In</button>
</form>

<script type="module">
import { start, evaluate } from 'https://<HIS_URL>/app/<YOUR_APP_ID>/js/engine.js';

await start('https://<HIS_URL>', '<YOUR_APP_ID>', { timeout: 10000 });

document.getElementById('login-btn').addEventListener('click', async () => {
    const token = await evaluate();
    document.getElementById('hid-token').value = token || '';
    document.getElementById('login-form').submit();
});
</script>

<form>
    <input type="email" id="email" placeholder="Email" required>
    <input type="password" id="password" placeholder="Password" required>
    <button type="button" id="login-btn">Log In</button>
    <p id="error" hidden></p>
</form>

<script type="module">
import { start, evaluate } from 'https://<HIS_URL>/app/<YOUR_APP_ID>/js/engine.js';

const reinit = () => start('https://<HIS_URL>', '<YOUR_APP_ID>', { timeout: 10000 });
await reinit();

document.getElementById('login-btn').addEventListener('click', async () => {
    const token = await evaluate();

    const response = await fetch('/login', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            email: document.getElementById('email').value,
            password: document.getElementById('password').value,
            hid_token: token
        }),
        signal: AbortSignal.timeout(10000)
    });

    if (response.ok) {
        window.location.href = '/dashboard';
    } else {
        document.getElementById('error').textContent = 'Invalid credentials';
        document.getElementById('error').hidden = false;
        await reinit();
    }
});
</script>

• <HIS_URL> is your Human Identity endpoint provided by the Wallarm team

• <YOUR_APP_ID> is your Application ID provided by the Wallarm team

In both examples, the token is sent to your backend along with the login request — as a hidden form field or a JSON body property. From there, it can be enforced by Wallarm's modules or by your own backend logic.

Step 3: Enforce the verdict¶

There are 2 approaches — choose based on your infrastructure:

Step 4: Test the integration¶

Verify that tokens are issued correctly:

1. Open your protected page in a browser and trigger the protected action.

2. In the browser DevTools (Network tab), verify that the evaluate request succeeds and returns a JWT.

3. Check that the JWT is attached to your request (as a hidden field, JSON property, or cookie — depending on your integration).

4. Test with a headless browser or automation tool — the verdict in the returned token should be "bot".

Verify that enforcement works:

• Wallarm modules: check that the hid cookie appears in requests passing through the Node. In Wallarm Console → API Sessions, confirm that sessions are grouped by hid. Then trigger a configured enforcement rule and verify that the session is added to the Session Denylist and subsequent requests are blocked.

• Your own backend: send a request with a "bot" verdict token and confirm your backend rejects it. Send a request with a "human" verdict token and confirm it passes.

Was this page helpful?

How can we improve this article? (Optional)

Information is unclear or confusing

Insufficient information

Outdated or incorrect information

0/240

Send