Skip to main content

​
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. After creation you will receive:
  • Public Key — used by the browser SDK. Safe to expose.
  • Secret Key — used to register your webhook and verify signatures. 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>
For authenticated users, pass a stable hashed identifier (never the raw user ID): 
<script type="module">
  const mod = await import('https://cdn.shieldlabs.ai/snippet.js?publicKey=YOUR_PUBLIC_KEY');
  mod.checkAuthenticatedUser('sha256_of_user_id');
</script>
The snippet uses session caching — it will not re-send a fingerprint if the session hasn’t changed. Use forceCheckAnonymous() or forceCheckAuthenticatedUser() to override.

​
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;
connect-src 'self' blob: *.shieldlabs.ai wss://*.shieldlabs.ai;
img-src     'self' data: https://rest.shieldlabs.ai;

​
4. Register a webhook endpoint

Tell ShieldLabs where to deliver the Trust Score: 
curl -X POST "https://api.shieldlabs.ai/YOUR_DOMAIN:YOUR_SECRET/callback" \
  -H "Content-Type: text/plain" \
  -d "https://your-server.com/shieldlabs/webhook"
Replace YOUR_DOMAIN (e.g. example.com) and YOUR_SECRET with your secret key.

​
5. Handle the webhook

ShieldLabs will POST to your endpoint within ~1 second of the browser check: 
{
  "Data": {
    "RequestID":       "550e8400-e29b-41d4-a716-446655440000",
    "DeviceID":        "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "VisitorID":       "7f3e9a12-...",
    "UserHID":         "sha256_of_user_id",
    "IP":              "93.184.216.34",
    "OS":              "Windows",
    "Country":         "US",
    "Score":           15,
    "Details":         [{ "Value": 15, "Description": "Is vpn by base ip" }],
    "LastRequestTime": "2026-04-14T10:00:00Z"
  },
  "Assing": "hmac-sha256-hex-signature"
}
Verify the signature before trusting the payload: 
// 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)
    return hmac.Equal([]byte(assing), []byte(hex.EncodeToString(mac.Sum(nil))))
}

// 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), Buffer.from(expected));
}

# Python
import hmac, hashlib, json
def verify_webhook(data: dict, assing: str, secret: str) -> bool:
    body = json.dumps(data, separators=(',', ':')).encode()
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, assing)

​
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();
});
ScoreRisk LevelRecommended Action
0–15LowAllow
16–39MediumMonitor
40–69ElevatedRequire 2FA / CAPTCHA
70–99HighBlock or manual review
100+BotBlock
999BannedRate limit exceeded (1h)

​
Next steps