Quickstart
Follow these steps to get your first Trust Score in minutes.
1. Create a domain in the Dashboard
Open dashboard.shieldlabs.ai → Domains → Add domain.
Enter your domain name only (e.g. example.com). After creation you will receive:
- Public Key — 32-character hex string for the browser SDK. Safe to expose.
- Secret Key — 32-character hex string for webhook verification and Pub API. Keep it secret.
2. Add the SDK to your site
Paste this script on every page you want to protect, replacing YOUR_PUBLIC_KEY:
<script type="module">
const mod = await import('https://cdn.shieldlabs.ai/snippet.js?publicKey=YOUR_PUBLIC_KEY');
mod.checkAnonymous();
</script>
<script type="module">
const mod = await import('https://cdn.shieldlabs.ai/snippet.js?publicKey=YOUR_PUBLIC_KEY');
mod.checkAuthenticatedUser('sha256_of_user_id');
</script>
Each call to checkAnonymous() or checkAuthenticatedUser() sends a new fingerprint. Use forceCheckAnonymous() or forceCheckAuthenticatedUser() to clear the session and force a fresh check.
3. Configure Content Security Policy
If your site uses a CSP header, add these directives:
script-src 'self' https://shieldlabs.ai https://cdn.shieldlabs.ai https://cdn.jsdelivr.net;
connect-src 'self' blob: *.shieldlabs.ai wss://*.shieldlabs.ai https://cdn.jsdelivr.net;
img-src 'self' data: https://rest.shieldlabs.ai;
4. Register a webhook endpoint
Tell ShieldLabs where to deliver the Trust Score via the Dashboard, or use the API:
curl -X PUT "https://account.shieldlabs.ai/api/domains/{domain_id}/webhook" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"callback": "https://your-server.com/shieldlabs/webhook"}'
curl -X POST "https://api.shieldlabs.ai/YOUR_DOMAIN:YOUR_SECRET/callback" \
-H "Content-Type: text/plain" \
-d "https://your-server.com/shieldlabs/webhook"
5. Handle the webhook
ShieldLabs will POST to your endpoint within ~1 second of the browser check:
{
"Data": {
"RequestID": "550e8400-e29b-41d4-a716-446655440000",
"SessionID": "7a1b2c3d-e89f-4a1b-9c2d-3e4f5a6b7c8d",
"CookieID": "3f2e1d0c-b9a8-7f6e-5d4c-3b2a1f0e9d8c",
"DeviceID": "6ba7b810-9dad-11d1-80b4-00c04fd430c9",
"VisitorID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"UserHID": "sha256_of_user_id",
"IP": "93.184.216.34",
"OS": "Windows",
"Country": "US",
"Score": 15,
"Details": [{ "Value": 15, "Description": "Is VPN" }],
"LastRequestTime": "2026-04-14T10:00:00Z",
"Phase": "initial"
},
"Assing": "hmac-sha256-hex-signature"
}
Data):
// Go
import ("crypto/hmac"; "crypto/sha256"; "encoding/hex"; "encoding/json")
func verifyWebhook(data WebhookData, assing, secret string) bool {
b, _ := json.Marshal(data)
mac := hmac.New(sha256.New, []byte(secret))
mac.Write(b)
expected := hex.EncodeToString(mac.Sum(nil))
return hmac.Equal([]byte(assing), []byte(expected))
}
// Node.js
import crypto from 'crypto';
function verifyWebhook(data, assing, secret) {
const body = JSON.stringify(data);
const expected = crypto.createHmac('sha256', secret).update(body).digest('hex');
return crypto.timingSafeEqual(
Buffer.from(assing, 'hex'),
Buffer.from(expected, 'hex')
);
}
6. Act on the score
// Express.js example
app.post('/shieldlabs/webhook', (req, res) => {
const { Data, Assing } = req.body;
if (!verifyWebhook(Data, Assing, process.env.SHIELD_SECRET)) {
return res.status(401).end();
}
const { Score, UserHID, RequestID } = Data;
if (Score >= 100) {
blockUser(UserHID);
} else if (Score >= 40) {
requireTwoFactor(UserHID);
}
res.status(200).end();
});
| Score | Risk Level | Recommended Action |
|---|
| 0–9 | Clean | Allow |
| 10–29 | Low | Allow / monitor |
| 30–59 | Medium | Monitor |
| 60–99 | High | Require 2FA / CAPTCHA |
| 100+ | Bot | Block |
| 999 | Banned | Rate limit exceeded (1h) |
Next steps
