Skip to main content
Every domain you add to ShieldLabs gets a public key, a secret key, and a private API key. They are scoped to that single domain and serve different purposes.

​
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 a fingerprint 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 (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.

​
Private API key

The Private API Key is the credential for the recommended History API. Find it in the dashboard API tab for your domain.
  • Send it as Authorization: Bearer sec_… to account.shieldlabs.ai/api/v1/….
  • Used to read scored snapshots by request_id, device_id, and other identifiers.
  • Does not go in the snippet or the browser.
  • Rotate it independently from the public/secret key pair from the dashboard API tab.

​
Secret key

The secret key authenticates the Management API on api.shieldlabs.ai — profile, balance, and the alternate billed History path.

Management API auth

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

Webhook verification

Webhooks are not signed with the Secret Key. Each endpoint you register in the dashboard Webhooks tab gets its own whsec_… signing secret. Verify the X-Shield-Signature header over the raw request body with that secret.
Never put the secret key or 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.

​
Keys are masked once issued

The full secret key is shown only at the moment it is created or rotated, in the dashboard. After that, you cannot read it back in plaintext anywhere. The free Profile endpoint on api.shieldlabs.ai returns the public and secret keys masked to the last four characters, so you can confirm which key a domain is using without exposing it. It costs 0 requests.
If you lose the secret key, rotate the key set and update your server. The Private API Key can be rotated separately from the API tab.

​
Rotating keys

After rotating the public/secret pair:
1

Update the snippet

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

Update your server

Swap the secret used for Management API auth to the new secret. Keep it in your secrets manager, not in code. Webhook endpoint secrets (whsec_…) are managed separately in the dashboard Webhooks tab.
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

Open app.shieldlabs.ai, select your domain:
  • Snippet tab — Public Key
  • API tab — Private API Key (History API)
  • API tab — Secret Key (Management API)

​
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 scored results through the History API.