Skip to main content

​
Domains

A domain is the unit of integration in ShieldLabs. You add each site you want to identify visitors on as its own domain, and that domain gets its own key set, its own webhook callback, and its own request totals. Nothing is shared across domains: a key set issued for one domain does not work on another. If you run a single site, you have one domain. If you run several sites (or staging and production), each is a separate domain with its own configuration.

​
Add a domain

Domains are created in the dashboard, on the Integration tab.
1

Open the Integration tab

Go to dashboard.shieldlabs.ai and open the Integration tab.
2

Add the domain

Enter the hostname you want to identify visitors on, for example myshop.com. Adding it provisions the domain’s public key, secret key, and an empty callback (webhook) slot.
3

Install the snippet

Drop the snippet onto that domain with its public key in the URL. See Install the snippet for the full client setup.
<script type="module">
  const mod = await import('https://cdn.shieldlabs.ai/snippet.js?publicKey=a3f8c2d1-e9b0-476a-8c5d-2f1e0b9a8c7d');
  mod.checkAnonymous();
</script>
4

Set the callback

Point the domain’s webhook callback at a handler on your server so scores are delivered to you. You can set it in the dashboard, or with the Management API. See Webhooks.
Adding a domain mints a fresh key set on the spot. The secret key is shown in full only at that moment. Capture it then and store it server-side. See Public and Secret Keys.

​
What every domain carries

FieldWhat it is
PublicKeyA UUID that goes in the snippet URL as ?publicKey=. Safe to expose in the browser. Identifies which domain a fingerprint belongs to.
SecretA 24-character lowercase alphanumeric string. Server-side only. Verifies the Assing webhook signature and authenticates Management API calls as {domain}:{secret}.
CallbackThe webhook URL each score is POSTed to. Empty until you set it.
EnabledWhether the domain is active. A disabled domain rejects identify calls and Management API auth with 401.
WeightThe domain’s remaining request balance, returned by the Profile endpoint. Across multiple domains, each carries its own balance. Billing is per request, counted per domain.
You can read the live configuration for a domain at any time with the Profile endpoint, which returns the keys masked to their last four characters so you can confirm a domain without exposing its credentials: 
curl "https://api.shieldlabs.ai/myshop.com:k7m2x9p4q8n5j3w6r1t0v8z2/profile"

{
  "Domain": "myshop.com",
  "Weight": 148230,
  "Callback": "https://myshop.com/webhooks/shieldlabs",
  "PublicKey": "************8c7d",
  "Secret": "************v8z2",
  "CreatedAt": "2025-11-21T18:00:21Z"
}
The Profile call is free: it does not consume any of the domain’s requests. Use it as a quick health check that a domain is enabled and pointed at the right callback. Weight is the domain’s remaining request balance.

​
Verification is automatic

You do not add a DNS record or upload a file to verify a domain. Verification happens on its own once live snippet traffic is seen.
1

Install the snippet with the domain's public key

The public key only works on the domain it was issued for. The server resolves the domain from the request Origin, then Referer, then Host, and checks it against the public key.
2

Trigger one identify call

Load a page that runs the snippet. The first fingerprint that arrives for that domain marks it as verified in the dashboard.
3

Confirm in the dashboard

The domain flips to verified on the Integration tab once that first call is recorded.
If a public key is served from a host it was not issued for, the identify call is rejected with 401, and the domain stays unverified. A key lifted from your page source will not work on someone else’s site.

​
Subdomains and host matching

A key set is scoped to the exact host you registered. The server resolves the domain from the request Origin, then Referer, then Host, and looks it up against the registered domains. The match is exact, with one normalization: a leading www. is stripped, so www.myshop.com and myshop.com resolve to the same domain. Subdomains do not inherit a parent domain’s key set. app.myshop.com and checkout.myshop.com are distinct hosts: each one you want to identify visitors on needs its own domain entry, with its own public key, secret key, and request totals.
Register each subdomain you serve the snippet on as its own domain. That keeps every host on its own key set and its own request balance, and lets you point each one at a different callback if you need to.

​
Per-domain isolation

Every domain is a self-contained unit. There is no key reuse across domains.

Separate credentials

Each domain has its own public key and secret key. A key set issued for one domain authenticates only that domain. Rotating one domain’s keys never touches another’s.

Separate callback

Each domain delivers its scores to its own callback URL. Point them at the same handler or different handlers, as you prefer.

Separate request totals

Requests are billed per domain. With multiple domains you can see how the balance splits across them. Billing is per request, not per user.

Independent enable state

Disabling one domain stops its identify calls and Management API access without affecting the others.
Do not reuse a key set across sites. Each domain gets the keys issued for it. A secret key forges webhook signatures and authenticates the Management API for its domain, so keep it server-side and use a different one per domain. See Public and Secret Keys.

​
Next steps

With the domain added, wire its public key into the snippet, keep its secret key on your server, and point its callback at a handler that verifies signatures per the webhooks guide.