Skip to main content
Read identification, risk signals and Risk Score on your server. Use the same package in Node.js backend routes and server handlers for Next.js, Nuxt and SvelteKit.

Before you start

Node.js 18+ with a Private API Key. The browser must already send an Identification ID to your server. For a fresh account, start with Quick Start. Register and verify the website domain in your dashboard. Use the same domain and environment as the browser check.

Get your credentials

Copy the domain’s Private API Key from Integration > API keys and store it as SHIELDLABS_API_KEY in your server environment. Resolve the registered domain’s public UUID with await shieldlabs.entities.domains() and store the matching id as SHIELDLABS_DOMAIN_ID. This UUID is different from the hostname and the API key. Pass it to each History read. For webhook verification, set SHIELDLABS_WEBHOOK_SECRET from Integration > Webhooks. Keep the API key and signing secret on your server. The SDK does not read environment variables automatically; pass them as shown below.

Install the SDK

Use yarn add or pnpm add with the same package and version if your project uses that package manager.

Add the integration

identifications.get(id, { domainId }) polls the current domain-scoped identification card within a bounded budget. A JSON-object 404 is treated as missing; other API failures remain errors. Do not generate a new browser identification just to retry a read of the same result. Keep unavailable risk or signals unverified; a missing score is not Score 0, and defaulted false flags do not prove that a check ran. The example policy refuses dangerous scores, browser automation, JavaScript-disabled checks, Banned IP, stale checks and reused IDs. Adapt the policy to the protected action. In production, atomically claim each accepted ID in shared durable storage, scoped to your tenant and domain, and enforce the expected user association. One identification authorizes one action. An in-memory set does not protect multiple server processes or survive restarts. The webhook signature covers the original raw bytes. Deduplicate accepted deliveries by event_id in durable storage. High-Risk Event group messages have a different payload; handle those separately from identification.scored.

Read lists and entity cards

Lists support identifications and user. Cards support identifications, user, visitor, device and ip. Keep the same filters, window and limit when following next_page_token; it is an opaque cursor. See History API for supported filters and cursor pagination. Use entities.list and entities.get for current History reads.

Map a Risk Score with riskBand

riskBand(score) labels one available identification score locally:
The 999 marker is separate from the three ordinary risk bands. Check availability and a finite numeric score first. The helper does not calculate the risk category of a user, visitor, device or IP; entity cards supply their own risk object. High-Risk Events and their confidence are separate from Risk Score.

Test the complete flow

  1. Send an Identification ID from a real browser check to the server on the same registered domain.
  2. Confirm the domain-scoped read returns that ID and an available Risk Score. If the result is still being processed, let the bounded read finish.
  3. Test a missing ID, unavailable risk/signals, a mismatched domain or user, a stale result and a reused accepted ID: none should authorize the action.
  4. For webhooks, verify the original raw body with its signature, then change one byte and confirm rejection. Deliver the same event_id again and confirm your handler processes it only once.
History entity cards expose available signal names, not weighted signal contributions. Use a verified scored webhook for the complete versioned identification payload and handle group events separately.

Troubleshooting

  • No result: verify the domain UUID, credential/environment match and that the browser finished sending its collectors. Retry reads of the same Identification ID within a bounded budget.
  • Unavailable risk or signals: keep the action unverified rather than substituting Score 0 or interpreting missing flags as clean.
  • Authentication error: use the Private API Key for History, not a Public Key, Management Secret Key or MCP OAuth token.
  • API error: preserve the returned status and body in server-side diagnostics before deciding the cause or retry policy.
  • Invalid webhook signature: verify the original raw bytes with the full endpoint signing secret before trusting parsed JSON.

Next steps