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.
Integration > API keys for example.com in the analytics dashboard: tabs Public Key, Private API Key (selected) and Secret Key; the Private API Key masked after its first characters, sec_6eo9l8 followed by dots; Active, last used 14m ago, 7d usage 11,020, a copy button and the Rotate icon.Integration > API keys for example.com in the analytics dashboard in the dark theme: tabs Public Key, Private API Key (selected) and Secret Key; the Private API Key masked after its first characters, sec_6eo9l8 followed by dots; Active, last used 14m ago, 7d usage 11,020, a copy button and the Rotate icon.

Integration > API keys in the analytics dashboard: one domain's Private API Key, masked, with tabs for Public Key, Private API Key and Secret Key.

​
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 identifications from the History API: one by request_id, or every identification of one user, device, visitor or IP by user_hid, device_id, visitor_id or ip. 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 Server API reference covers the account read in full.

​
Secret Key

The Secret Key authenticates the Management API on api.shieldlabs.ai: the profile, which includes the remaining included volume on your account.

Management API auth

Recommended: X-Shield-Domain + Authorization: Bearer headers on api.shieldlabs.ai/v1/….

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

The free Profile endpoint on api.shieldlabs.ai returns the Public Key and the Secret Key masked to the last four characters, so you can confirm which key a domain uses without exposing it. It never counts against your plan.
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, the Secret Key for Management API auth. Keep it in your secrets manager, not in code. Webhook endpoint secrets (whsec_…) are managed separately, per endpoint, under Integration > Webhooks.
3

Confirm with Profile

Call the Profile endpoint and check that the masked tails match the new keys.
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 (Management API), 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.