Environments

In ShieldLabs you separate development from production the same way you separate any other configuration: with a separate domain and key set for each environment. Every environment loads the same snippet from cdn.shieldlabs.ai. The API shape is identical in every environment. A webhook from a development domain and a webhook from a production domain carry the same fields, the same request_id join key, and the same Risk Score (0-100) with its signals. Nothing about the integration changes between environments except the domain and its credentials.

One thing changes per environment

The domain and its key set

Register a separate domain for each environment (for example dev.example.com and example.com). Each domain gets its own Public Key, Private API Key, Secret Key and webhook endpoints. Every environment loads the snippet from cdn.shieldlabs.ai.

Use a separate domain and key set per environment

Register each environment as its own domain in the analytics dashboard. Every domain you add gets its own Public Key, Private API Key and Secret Key and its own webhook endpoints. A development domain uses one of your plan’s domain slots: Free and Starter allow 1 domain, Growth 3, Scale 5. On Free and Starter the development domain takes your only slot, so delete it before you add the production domain; deleting a domain frees its slot right away.

Environment	Registered domain	Webhook endpoints
Development	`dev.example.com`	your tunnel or staging URLs
Production	`example.com`	your production handlers

Keeping them separate buys you:

Clean data. Development traffic stays on its own domain, so when you pick your production domain in the analytics dashboard’s domain picker instead of All domains, its users, devices, High-Risk Events and traffic sources reflect live traffic only.
Isolated webhooks. Each domain registers its own webhook endpoints, so test deliveries hit your local handler and never your production endpoint.
One shared quota. Identifications on the development domain count against your account’s included identifications like any other, so keep test traffic small. Billing is per identification.
Blast-radius control. A leaked development secret cannot call the Server API for your production domain. Keys are scoped to a single domain. Webhook whsec_… secrets are scoped per endpoint.

The period and domain row of the analytics dashboard with Last 7 days (Sep 20 to Sep 26) selected and the domain menu open: All domains with 12,480 identifications, example.com 11,020, dev.example.com 1,460 and shop.example.com 0. — Pick the period and one domain or all domains in the analytics dashboard.

The period and domain row of the analytics dashboard in the dark theme with Last 7 days (Sep 20 to Sep 26) selected and the domain menu open: All domains with 12,480 identifications, example.com 11,020, dev.example.com 1,460 and shop.example.com 0. — Pick the period and one domain or all domains in the analytics dashboard.

Register the development host as its own domain, and do not reuse one key set across environments. While example.com accepts subdomains (the default), a page on dev.example.com that loads the production Public Key is accepted and its traffic lands in production. Once dev.example.com is its own domain, the production key is rejected there with a 401. A single secret shared across environments also means a development leak compromises production.

Wire the keys through config

Load the Public Key from environment config instead of hardcoding it, so the same build runs in both environments. Keep the Private API Key (for History API reads) and the Secret Key (for the Management API) server-side only, and store each webhook whsec_… for signature verification. None of them may reach the browser.

NEXT_PUBLIC_SHIELDLABS_PUBLIC_KEY=YOUR_DEV_PUBLIC_KEY   # public, safe in the browser build
SHIELDLABS_DOMAIN=dev.example.com
SHIELDLABS_PRIVATE_API_KEY=sec_YOUR_DEV_PRIVATE_API_KEY   # server-side only, History API reads
SHIELDLABS_SECRET=YOUR_DEV_SECRET   # server-side only, Management API
SHIELDLABS_WEBHOOK_SECRET=whsec_...   # server-side only, dev endpoint

NEXT_PUBLIC_SHIELDLABS_PUBLIC_KEY=YOUR_PROD_PUBLIC_KEY   # public, safe in the browser build
SHIELDLABS_DOMAIN=example.com
SHIELDLABS_PRIVATE_API_KEY=sec_YOUR_PROD_PRIVATE_API_KEY   # server-side only, History API reads
SHIELDLABS_SECRET=YOUR_PROD_SECRET   # server-side only, Management API
SHIELDLABS_WEBHOOK_SECRET=whsec_...   # server-side only, prod endpoint

A framework component then reads the Public Key from config and loads the module the same way in every environment. Pass the hashed User HID when the user is signed in:

ShieldLabsTracker.jsx

'use client';
import { useEffect } from 'react';

// Public value, safe to expose in the browser build.
const PUBLIC_KEY = process.env.NEXT_PUBLIC_SHIELDLABS_PUBLIC_KEY;

export function ShieldLabsTracker({ hashedUserId }) {
  useEffect(() => {
    let cancelled = false;
    (async () => {
      const mod = await import(
        /* webpackIgnore: true */
        `https://cdn.shieldlabs.ai/snippet.js?publicKey=${PUBLIC_KEY}`
      );
      if (cancelled) return;
      hashedUserId
        ? mod.checkAuthenticatedUser(hashedUserId)
        : mod.checkAnonymous();
    })();
    return () => { cancelled = true; };
  }, [hashedUserId]);

  return null;
}

Your Content-Security-Policy is the same in every environment: https://cdn.shieldlabs.ai in script-src, and https://rest.shieldlabs.ai, wss://rest.shieldlabs.ai, https://webrtc.shieldlabs.ai and stun:ice.shieldlabs.ai:3478 in connect-src. If the page includes the <noscript><img> beacon, also allow https://rest.shieldlabs.ai in img-src. If a policy blocks https://webrtc.shieldlabs.ai, identifications still arrive but can carry the stun_not_checked risk signal (weight 30).

Receiving webhooks in development

Your development webhook needs a publicly reachable URL. Run a tunnel to your local server and register it as an endpoint for the development domain under Integration > Webhooks in the analytics dashboard:

# expose your local server
ngrok http 3000
# -> https://abc123.ngrok.app

Add https://abc123.ngrok.app/webhooks/shieldlabs as an endpoint in the analytics dashboard, copy that endpoint’s whsec_… secret into SHIELDLABS_WEBHOOK_SECRET, and verify X-Shield-Signature exactly as you will in production. The Webhooks guide carries the verification logic, the single webhook per scored identification (ShieldLabs waits for follow-up network checks, at most about 10 seconds, then sends the final Risk Score once), and the at-most-once delivery caveat.

Webhooks are at-most-once with no retries, so a tunnel that is down means a missed delivery. When your local handler is offline, read results back with the History API using that domain’s Private API Key. Make handlers idempotent on request_id either way.

Test with real traffic before production

Risk Scores reflect the actual connection and browser environment of whoever loads the page, so the most useful test is real traffic on a real development domain, not synthetic requests.

Deploy the snippet on a development domain

Register dev.example.com, load the snippet with the development domain’s Public Key on a staging or preview deployment, and let real traffic flow through it. Pick a hostname that resolves in public DNS, such as a staging or preview subdomain: adding a domain checks that the hostname exists, and a page served from localhost has no registered domain to match, so its identification calls get 401.

Watch the data land

Confirm identifications appear under your development domain in the analytics dashboard and that webhooks reach your tunnel. Sign in with a test account so the identifications carry a User HID, and check that user_hid arrives on the webhook. Check the signals array to see which risk signals fired and why. Within one visit, the snippet runs at most one identification every five minutes for the same user; call forceCheckAnonymous or forceCheckAuthenticatedUser when a test needs a new identification on demand.

Check your actions against the bands

Choose the action for each band (Trusted 0-29, Suspicious 30-59, Dangerous 60-100) and verify the behavior on this real traffic, the way acting on results lays out.

Promote to production

Swap the keys to the production domain’s key set through config (on Free and Starter, delete the development domain first so the production domain has a slot). Nothing else in your code changes.

Read a high Risk Score together with its named risk signals and the user’s history. A real customer on a corporate VPN can reach the Suspicious band; the signals show why, and you choose the action for each case. Testing with real traffic on a development domain shows you that distribution before you act on it.

Promotion checklist

Public Key

Use the production domain’s Public Key in the snippet URL.

Private API Key

Load the production Private API Key on your server for History API reads. It must never reach the browser.

Secret Key

Load the production Secret Key on your server for Management API auth on api.shieldlabs.ai. It must never reach the browser.

Webhook endpoints

Register production webhook endpoints for the production domain under Integration > Webhooks, not your development tunnel.

Webhook signing secrets

Copy each production endpoint’s whsec_… into your server environment for webhook verification.

CSP

Confirm your production Content-Security-Policy carries every ShieldLabs host in script-src and connect-src.

Next steps

API keys

Where each key lives and why server keys never ship to the browser.

Domains

Webhooks

Verify X-Shield-Signature and handle the single scored webhook per identification.

Acting on results

Choose the action for each band: allow, step up, review or block.

Getting started

Web

Server

Core concepts

Detection

Analytics dashboard

Frontend

Backend

Billing and usage

Security and privacy

Troubleshooting

Resources

Support

Legal

One thing changes per environment

The domain and its key set

Use a separate domain and key set per environment

Wire the keys through config

Receiving webhooks in development

Test with real traffic before production

Promotion checklist

Next steps

API keys

Domains

Webhooks

Acting on results

​One thing changes per environment

The domain and its key set

​Use a separate domain and key set per environment

​Wire the keys through config

​Receiving webhooks in development

​Test with real traffic before production

​Promotion checklist

​Next steps

API keys

Domains

Webhooks

Acting on results

One thing changes per environment

Use a separate domain and key set per environment

Wire the keys through config

Receiving webhooks in development

Test with real traffic before production

Promotion checklist

Next steps