> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shieldlabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup

> An overview of everything you wire up to run ShieldLabs: the snippet, keys, webhooks, and domains.

ShieldLabs is a snippet, a webhook, and a read API. The browser snippet collects 100+ browser, device, and network signals and posts them to ShieldLabs automatically. The server derives a persistent identity and an explainable **Risk Score (0-100)**, then delivers it to your backend by [webhook](/setup/webhooks) (and you can read it back any time from the [Server API](/api/server-api)). Your own code reads the score plus its `signals` and decides allow, challenge, review, or block. ShieldLabs scores; you decide.

Most teams get their first Risk Score in about **5 minutes**.

## Integration checklist

<Steps>
  <Step title="Create a domain and get your keys">
    [Sign up for free](https://app.shieldlabs.ai/) and get 5,000 identifications, or log in if you already have an account, then register the domain you want to identify visitors on. ShieldLabs issues a **Public Key** (per domain, safe to put in the browser) plus server-side credentials — a **Private API Key** for the [History API](/api/server-api) and a **Secret Key** for the Management API. Each webhook endpoint you add in the dashboard gets its own `whsec_…` signing secret. The [Keys](/setup/keys) and [Domains](/setup/domains) pages cover them.
  </Step>

  <Step title="Install the snippet">
    Load the ES module from `cdn.shieldlabs.ai` with your Public Key and call `checkAnonymous()`. It is a dynamic `import()`, not an npm package and not a native SDK, web only. The [Snippet](/setup/snippet) page has framework examples for Native JS, React, Angular, Vue, Preact, and Svelte.

    ```html theme={null}
    <script type="module">
      const mod = await import('https://cdn.shieldlabs.ai/snippet.js?publicKey=YOUR_PUBLIC_KEY');
      mod.checkAnonymous();
    </script>
    ```
  </Step>

  <Step title="Allow the hosts in your CSP">
    If you run a Content Security Policy, allow the ShieldLabs CDN and the endpoints the snippet posts to per the [CSP](/setup/csp) directives. Without this the snippet is blocked and you receive no signals.

    ```http theme={null}
    Content-Security-Policy:
      script-src 'self' https://cdn.shieldlabs.ai https://cdn.jsdelivr.net;
      connect-src 'self' https://rest.shieldlabs.ai https://webrtc.shieldlabs.ai stun:ice.shieldlabs.ai:3478;
    ```
  </Step>

  <Step title="Register a webhook">
    Point ShieldLabs at one or more backend URLs so scores are pushed as they are computed. Add endpoints in the dashboard **Webhooks** tab (up to 10 per domain). Each endpoint has its own `whsec_…` signing secret; verify the `X-Shield-Signature` header on the raw request body as the [Webhooks](/setup/webhooks) guide details.
  </Step>

  <Step title="Verify the score, then act on it">
    Trigger an identify call (load a page with the snippet), confirm your webhook receives the scored event in about a second, and verify the signature. Read `score` and `signals`, then your code decides what to do. There is no in-product rules engine: the decision lives in your application, where [acting on the Risk Score](/guides/acting-on-risk-score) walks the allow, challenge, review, or block paths.
  </Step>
</Steps>

<Tip>
  Want the fastest path end to end? The [Quickstart](/quickstart) walks the same five steps with copy-paste snippets and a working webhook handler.
</Tip>

## Setup pages

<CardGroup cols={2}>
  <Card title="Snippet" icon="code" href="/setup/snippet">
    Install the ES-module snippet, the `checkAnonymous` and `checkAuthenticatedUser` exports, framework examples, and what gets collected.
  </Card>

  <Card title="Keys" icon="key" href="/setup/keys">
    Public Key vs Secret Key: where each one goes, what it authenticates, and how to keep the secret out of the browser.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/setup/webhooks">
    Register endpoints in the dashboard, verify `X-Shield-Signature`, and handle the flat scored payload.
  </Card>

  <Card title="CSP" icon="shield-halved" href="/setup/csp">
    The exact `script-src` and `connect-src` directives the snippet needs.
  </Card>

  <Card title="Domains" icon="globe" href="/setup/domains">
    Register a domain, how the snippet ties traffic to it, and managing multiple domains under one account.
  </Card>

  <Card title="Environments" icon="layer-group" href="/setup/environments">
    Separate staging and production with distinct domains and keys so test traffic never mixes with live data.
  </Card>
</CardGroup>

## What you receive

Once the snippet is live and your webhook is registered, every identify call produces an event like this. The `signals` array names each signal that fired and the points it contributed, so the score is explainable, not a black box.

```http theme={null}
POST https://yourapp.com/webhooks/shieldlabs
Content-Type: application/json
X-Shield-Signature: sha256=1f3c9a...hex-hmac-sha256

{
  "request_id": "8f1d0c2a-7b3e-4a9c-9d2f-1e6a5b4c3d21",
  "visitor_id": "c4a2e9b1-5f8d-4c3a-8e7b-2a1f0d9c8b76",
  "device_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "user_hid": "hashed-account-id",
  "public_ip": { "ip": "203.0.113.42", "country": "US" },
  "os": "Mac OS X",
  "risk_score": 40,
    "signals": [
    { "name": "OS not Detected", "weight": 30 },
    { "name": "Datacenter IP", "weight": 10 }
  ],
  "observed_at": "2026-06-16T10:00:00Z"
}
```

The Score runs 0 to 100, capped at 100, and sorts into four bands (Clean, Low, Medium, High) that the [Risk Score](/features/risk-scoring) page defines in full. The bands are a guide; the action per band is yours to write in your own code.

<Note>
  A legitimate visitor can score high (a corporate proxy, a VPN, or a privacy browser). Decide on the Score plus the `signals` plus your action context, never the number alone, and the playbook for [acting on the Risk Score](/guides/acting-on-risk-score) shows how to tune your thresholds gradually.
</Note>

<Warning>
  [Webhooks](/setup/webhooks) are **at-most-once** with no retries and a roughly 1-second timeout. Make your handler idempotent on `request_id`, and for guaranteed reads poll the [History API](/api/server-api) rather than relying on the webhook alone.
</Warning>

## Where to go next

With the snippet installed and a webhook verified, read the [Overview](/overview) to understand the identifiers and the [Risk Score](/features/risk-scoring), then jump into the [Cookbook](/use-case) for worked examples like [login and 2FA](/use-case/step-up-authentication), [checkout](/use-case/payment-fraud), and [affiliate fraud](/use-case/affiliate-fraud). The [API overview](/api/overview) has the full payloads and endpoints.