Quick Start

Sign up for free and get 5,000 identifications, or log in if you already have an account. Then follow these steps to your first Risk Score.

Create an account

In the dashboard, create a domain (for example myshop.com) — no credit card required. Each domain gets its own key pair:

Key	Where it lives	Purpose
Public Key	In the browser, in the snippet URL	Safe to expose. Identifies the domain on the identify call.
Private API Key	Backend only (`sec_…`)	Authenticates the History API to read scored results.
Secret Key	Backend only, never in the browser	Authenticates the Management API (profile and balance).
Webhook signing secret	Backend only (`whsec_…` per endpoint)	Verifies the `X-Shield-Signature` header on incoming webhooks. Copy from the dashboard Webhooks tab.

The Secret Key and each webhook whsec_… secret stay on the backend, like a database password. See Keys and Webhooks.

Install the snippet

The snippet is an ES module loaded from the CDN with a dynamic import(). It runs in the browser only.Drop this into your page and swap in your Public Key.

<script type="module">
  const mod = await import(
    'https://cdn.shieldlabs.ai/snippet.js?publicKey=YOUR_PUBLIC_KEY'
  );

  // Anonymous visitor:
  mod.checkAnonymous();

  // Logged-in user (pass a HASHED / pseudonymous id, never a raw email or user id):
  // mod.checkAuthenticatedUser('a1b2c3d4hasheduserid');
</script>

The snippet POSTs the signals automatically and returns a Promise. The browser computes no VisitorID, DeviceID, or Risk Score. Those come back server-side.The signature is checkAnonymous(userHID?, callback?) and checkAuthenticatedUser(userHID, callback?). The optional callback fires after the POST and gives you the client ip and the requestID. Use the requestID to correlate this check with the webhook you receive — forward it to your backend (shown below) so your server can match the webhook or read the History API for this visit. The first argument is the client IP, not the score. The Risk Score arrives later by webhook.

// Anonymous: pass undefined for userHID so the callback lands in the right slot.
mod.checkAnonymous(undefined, (ip, requestID) => {
  // Forward the requestID to your backend so the server can match the webhook
  // (or read the History API) for this visit. The score never reaches the browser.
  fetch('/api/track-request', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ requestID }),
  });
});

// Authenticated:
// mod.checkAuthenticatedUser('a1b2c3d4hasheduserid', (ip, requestID) => {
//   fetch('/api/track-request', { method: 'POST',
//     headers: { 'Content-Type': 'application/json' },
//     body: JSON.stringify({ requestID }) });
// });

Copy-paste versions for Native JS, React, Angular, Vue, Preact, and Svelte live at Install the snippet.

Want to confirm it works right now? Load a page with the snippet, then open your dashboard. The visit and its Risk Score show up within a few seconds — the fastest check before you wire the score into your own backend (the webhook below, or a read from the History API).

This step wires the score into your own backend. (If you only wanted to see it work, the dashboard check above already did that.)Register an endpoint in the dashboard (Webhooks tab on your domain). Within about 1 second of the browser check, ShieldLabs POSTs a JSON event to that URL. The signature travels in the X-Shield-Signature header, not in the body.

POST https://myshop.com/webhooks/shieldlabs
Content-Type: application/json
X-Shield-Signature: sha256=3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e

{
  "event_type": "identification.scored",
  "schema_version": "2026-06-01",
  "created_at": "2026-06-16T18:00:21Z",
  "data": {
    "request_id": "13f84f05-2c4a-4d8e-9b1a-6f2e7c9d0a55",
    "device_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "visitor_id": "161dfbad-e5f6-7890-abcd-ef1234567890",
    "user_hid": "a1b2c3d4hasheduserid",
    "public_ip": { "ip": "203.0.113.42", "country": "US" },
    "connection_type": "browser_vpn_proxy",
    "risk_score": 40,
    "signals": [
      { "name": "browser_vpn_proxy", "weight": 30 },
      { "name": "timezone_mismatch", "weight": 10 }
    ],
    "observed_at": "2026-06-16T18:00:21Z"
  }
}

Each signal name is a stable slug — branch on name, detection_flags, and risk_score, not on display labels from the History API.

Always verify X-Shield-Signature before trusting the payload. It is sha256= plus the hex HMAC-SHA256 of the raw request body, keyed with that endpoint’s whsec_… signing secret.

Node.js

import crypto from 'crypto';
import express from 'express';

const SECRET = process.env.SHIELDLABS_WEBHOOK_SECRET; // whsec_… for this endpoint
const app = express();

app.use(express.json({ verify: (req, _res, buf) => { req.rawBody = buf; } }));

app.post('/webhooks/shieldlabs', (req, res) => {
  const received = req.get('X-Shield-Signature') ?? '';
  const expected =
    'sha256=' +
    crypto.createHmac('sha256', SECRET).update(req.rawBody).digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(received);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.sendStatus(401);
  }

  res.sendStatus(200);
  handleScore(req.body); // idempotent on request_id
});

HMAC the raw request body bytes as received. Re-serializing the parsed JSON changes the bytes and the signature will not match.

Two behaviors to handle up front:

One webhook per scored identification. The server waits up to ~60s for optional follow-up network checks, then sends the final score once. When no follow-up is expected, it arrives in about a second.
There are no retries. Delivery is at-most-once. Make your handler idempotent on request_id, and poll the History API for guaranteed reads.

More detail lives in Webhooks.

Act on the Risk Score

The Risk Score is 0 to 100, capped at 100. Higher means more anonymous, more likely masked, spoofed, or abusive. Every score ships with signals, so you see which signals fired.Decide what to do per band. These are recommendations, not enforced rules. Your code owns the verdict.

Band	Range	Meaning	What your code might do
Clean	0–9	No meaningful signals	Pass through, no friction
Low	10–29	One minor signal	Allow, worth logging
Medium	30–59	Several overlapping or one moderate signal	Step-up challenge, second look, or review
High	60–100	Strong anonymity signals	Block, review, or require verification

async function handleScore(payload) {
  const { request_id, score, signals, user_hid } = payload;

  // Idempotent: a redelivery may carry the same request_id.
  await db.checks.upsert({ requestID: request_id, score, signals });

  if (score >= 60) {
    await requireStepUp(user_hid);        // High: verify before a sensitive action
  } else if (score >= 30) {
    await flagForReview(user_hid, score); // Medium: a second look
  }
  // Clean / Low: allow.
}

A legitimate user can score high (corporate proxy, VPN, or a privacy browser). Decide on Score + signals + action context, never the number alone. Tune thresholds gradually.

Next steps

Identification

Persistent VisitorID and DeviceID, and how they survive cleared cookies.

Anonymity Signals

VPN, proxy, Tor, and anti-detect browser signals, with the scoring reference.

Risk Scoring

How the 0 to 100 score is built, what signals contains, and the bands.

Patterns

Ready-made patterns computed across your historical traffic. They refresh periodically, so newly seen entities surface after a short delay, not instantly.

Traffic Analytics

Rank every source by the risk and anonymous-traffic share it delivers.

Acting on the Risk Score

Turn the score and signals into allow, challenge, review, and block logic.

Getting started

Features

Frontend

Backend

Billing and usage

Security and privacy

Troubleshooting

Resources

Support

Legal

Next steps

Identification

Anonymity Signals

Risk Scoring

Patterns

Traffic Analytics

Acting on the Risk Score

​Next steps

Identification

Anonymity Signals

Risk Scoring

Patterns

Traffic Analytics

Acting on the Risk Score

Next steps