Multi-Accounting

<script type="module">
  const mod = await import(
    'https://cdn.shieldlabs.ai/snippet.js?publicKey=YOUR_PUBLIC_KEY'
  );
  // On the page with the action, in place of the plain check: a fresh
  // identification, started when the page opens so it is sent while the user
  // reads it. onInitialized fires when the check starts, before the snippet
  // sends it, so it only stores the request ID and the form submits normally.
  // Pass the hashed account id, never a raw email or user id.
  mod.forceCheckAuthenticatedUser('8a9f-hashed-account-id', {
    onInitialized: (result) => {
      if (result.status === 'initialized') {
        document.getElementById('shieldlabs-request-id').value = result.requestID;
      }
    },
  });
</script>

<form id="action-form" method="POST" action="/api/account-action">
  <input type="hidden" id="shieldlabs-request-id" name="shieldlabsRequestId" />
  <button type="submit">Continue</button>
</form>

{
  "request_id": "13f84f05-7c2a-4e9b-9f1d-2a6b8c0e4d11",
  "device_id": "5eb7fd5c-2a1b-4c3d-9e8f-7a6b5c4d3e2f",
  "visitor_id": "161dfbad-8e7f-4a6b-9c5d-0e1f2a3b4c5d",
  "user_hid": "8a9f...hashed-account-id",
  "public_ip": { "ip": "203.0.113.42", "country": "US" },
  "local_ip": { "ip": "198.51.100.23", "country": "US" },
  "risk_score": 20,
  "signals": [
    { "name": "proxy", "weight": 10 },
    { "name": "datacenter_ip", "weight": 10 }
  ],
  "detection_flags": { "proxy": true, "datacenter_ip": true, "ip_mismatch": true },
  "observed_at": "2026-06-16T18:00:45Z"
}

app.post('/api/account-action', async (req, res) => {
  const { shieldlabsRequestId } = req.body;
  const userHid = req.user.hashedId; // the hashed id you pass to the snippet

  // 1. The guard: read the identification (cache, then History fallback).
  const risk = await waitForScore(shieldlabsRequestId, 2000);
  if (!risk) {
    return res.status(200).json({ requireVerification: true, reason: 'no_identification' });
  }
  if (risk.user_hid !== userHid) {
    return res.status(200).json({ requireVerification: true, reason: 'identification_mismatch' });
  }
  if (risk.risk_score > 100) {
    return res.status(200).json({ requireVerification: true, reason: 'rate_limit_marker' });
  }

  // 2. The all-zero Device ID means no usable device signals reached ShieldLabs:
  //    there is no device to count accounts on, so route it to verification.
  if (risk.device_id === NIL_DEVICE) {
    return res.status(200).json({ requireVerification: true, reason: 'no_usable_device' });
  }

  // 3. Count the distinct accounts that have appeared on this one device.
  //    accountsBehindDevice reads the newest 100 identifications and leaves out
  //    "anonymous". For a high-traffic device, keep the set in your own store (see note).
  //    A failed History read is unverified: route it to verification.
  const accountsOnDevice = await accountsBehindDevice(risk.device_id).catch(() => null);
  if (accountsOnDevice === null) {
    return res.status(200).json({ requireVerification: true, reason: 'history_unavailable' });
  }

  // 4. Accounts with a Multi-accounting event, recorded when it arrives through
  //    the API or webhooks or when you review it in the analytics dashboard:
  //    null, 'medium' or 'high' (your own store).
  const watched = await multiAccountingWatchlist.get(userHid);

  // 5. Choose the action for each case. Branch on the count, your watchlist and
  //    the band; signals[].name slugs are stable if one signal matters on its own.
  //    Tune YOUR_ACCOUNT_LIMIT against your own traffic.
  if (watched === 'high') {
    return res.status(200).json({ requireVerification: true, reason: 'held_for_review' });
  }
  if (watched || accountsOnDevice >= YOUR_ACCOUNT_LIMIT) {
    return res.status(200).json({ requireVerification: true, reason: 'many_accounts_one_device' });
  }
  if (band(risk.risk_score) === 'Dangerous') {
    return res.status(200).json({ requireVerification: true, reason: 'masked_session' });
  }

  return allow(req, res);
});

curl "https://account.shieldlabs.ai/api/v1/history/device_id/5eb7fd5c-2a1b-4c3d-9e8f-7a6b5c4d3e2f?limit=100" \
  -H "Authorization: Bearer sec_your_private_api_key"