Skip to main content
Every domain you add to ShieldLabs gets three keys: a Public Key, a Private API Key and a Secret Key. They are scoped to that single domain and serve different purposes. Each webhook endpoint also carries its own signing secret.

Public Key

The Public Key is the only credential that ships to the browser, and exposing it there is by design.
  • Goes in the snippet URL as the ?publicKey= query parameter.
  • Tells rest.shieldlabs.ai which domain an identification belongs to.
  • Safe to expose. It is visible in your page source and cannot read data, change settings, or authenticate against any server API.
  • The request is only accepted when the Public Key matches the domain it is served from, or a subdomain of it while the domain accepts subdomains (the default; see Domains). The domain is resolved from the Origin, Referer, or Host. A Public Key lifted from your page will not work on someone else’s domain.
Install the snippet covers the full client setup, including checkAuthenticatedUser for signed-in users.

Private API Key

The Private API Key is the credential for the recommended History API. In the analytics dashboard, open Integration > API keys and select the domain.
  • Send it as Authorization: Bearer sec_… to account.shieldlabs.ai/api/v1/….
  • Reads one identification, or a user list, with the domain id from GET /api/v1/domains. Visitor, device, and IP are one record each. The key reads only its own domain.
  • Stays on your server: it never goes in the snippet or the browser.
  • Rotate it on its own, without touching the Public Key and Secret Key, under Integration > API keys.
The Search reference covers the account read in full.

Secret Key

The Secret Key is a server-side credential for the domain. Keep it out of the browser and rotate it under Integration > API keys.

History API

Read identifications with the Private API Key on account.shieldlabs.ai.

Webhook verification

Each webhook endpoint you register under Integration > Webhooks in the analytics dashboard signs with its own whsec_… secret, separate from the Secret Key. Verify the X-Shield-Signature header over the raw request body with that secret.
Never put the Secret Key or the Private API Key in client-side code, a snippet, a mobile app bundle, a public repository, or any place a browser can reach. Store them in environment variables or a secrets manager. Store each webhook whsec_… the same way.

Check which keys a domain uses

In the analytics dashboard, Integration > API keys shows one key type at a time, with a row per domain: the Public Key in full, the Private API Key and the Secret Key masked, each with a copy button that copies the full key. Rotate replaces a key, and the previous key stops working. You rotate the Public Key, the Private API Key and the Secret Key separately. If the Secret Key may have been exposed, rotate it and update your server.

Rotating keys

After rotating a key:
1

Update the snippet (Public Key)

Replace the ?publicKey= value in your snippet (or the environment variable that feeds it) with the new Public Key.
2

Update your server (Private API Key or Secret Key)

Swap the rotated key on your server: the Private API Key for History API reads, and the Secret Key wherever your server stores it. Keep it in your secrets manager, not in code. Webhook endpoint secrets (whsec_…) are managed separately, per endpoint, under Integration > Webhooks.
3

Verify the updated integration

Confirm that the updated Public Key sends identifications from your site. For a Private API Key, make a History request. Check the Secret Key under Integration > API keys and update any server configuration that stores it. For a webhook signing secret, verify a fresh signed test delivery.
Rotate keys whenever a credential may have been exposed (a leaked log, a committed .env, an offboarded teammate) and on a routine schedule for sensitive domains.

Where to find your keys

In the analytics dashboard (app.shieldlabs.ai), open Integration and select your domain (Integration describes each tab):
  • Install: the snippets, with the Public Key already in them
  • API keys: the Public Key, the Private API Key (History API) and the Secret Key, each with a copy button and Rotate
  • Webhooks: each endpoint with its whsec_… signing secret

Next steps

Wire the Public Key into the snippet, register webhook endpoints and verify each endpoint’s whsec_… secret per the webhooks guide, and read results, including every identification of one user, through the History API.