Skip to main content
ShieldLabs scores your users, devices, visitors and IP addresses. Each time the snippet runs, it makes one identification: ShieldLabs returns its Risk Score with every risk signal named and weighted, and links it to the device, visitor, public IP and local IP it belongs to, and to the user when a signed-in page passes a User HID. Your backend receives each identification by webhook and reads any identification, or every identification of one account, device, visitor or public IP, through the History API. You choose the action for each case (allow, step up, review or block) and act on the result in your backend.

​
The three surfaces

JS snippet

Collects device and network signals in the browser and posts each identification to rest.shieldlabs.ai automatically. On signed-in pages, checkAuthenticatedUser passes the hashed User HID. You install it once; you do not call this endpoint yourself.

Webhooks

Push delivery. ShieldLabs POSTs each identification’s Risk Score and named risk signals to every endpoint you register in the analytics dashboard, about 300 ms after the check in the browser.

Server API

Pull. Read any identification by its request ID, or every identification of one user, device, visitor or public IP (History API), and the remaining included volume on your account (Management API).
A typical integration uses all three: the snippet runs on your pages and passes a hashed User HID on signed-in pages, webhooks deliver each identification about 300 ms after the check, and the History API is your guaranteed read and your view of an account’s history.

​
What the API returns

Each webhook and each History row is one identification, the event layer under your users, devices, visitors and IPs. It carries the keys that link it to each of them, so the account-level view is one lookup away. High-Risk Events (Multi-accounting, Account sharing, Impossible travel and Account takeover, each at Medium or High confidence) are detected on your users and are available in the analytics dashboard, the API and webhooks. In the analytics dashboard, Overview shows how many of your users have each one, Analytics filters by them, and the user card shows each event with its confidence. Pass a hashed User HID with checkAuthenticatedUser on every signed-in page. Users, account-level risk and all four High-Risk Events are built on it. Users, devices, visitors and IPs explains the model.

​
Hosts

For development and staging, register a separate domain (for example dev.example.com) and call the same hosts with that domain’s keys. The environments guide walks through it.

​
Authentication

Each domain has three keys, one for the browser and two for your backend, plus a signing secret for each webhook endpoint. They are not interchangeable. History API (recommended for reads):
Management API (profile and included volume):
Private API Keys and Secret Keys must never appear in the browser, the snippet, client logs, or a public repository. If one leaks, rotate it in the analytics dashboard under Integration > API keys with Rotate (Integration). The API keys page covers where each credential belongs.

​
Asynchronous scoring

Scoring is asynchronous. The snippet posts the collected signals and receives an acknowledgment; ShieldLabs scores the identification in about 300 ms and delivers the result by webhook and through the History API. The request_id ties the snippet call, its webhook and its History record together, and the user_hid, device_id, visitor_id and IP fields tie the identification to your users, devices, visitors and IPs.

​
Billing and limits

  • Each identification uses 1 of your account’s included identifications. All your domains share one quota.
  • Reading your profile, receiving webhooks, using the analytics dashboard and History API reads are free.
  • The History API defaults to 20 rows and accepts a limit up to 100, with offset for paging.
  • When your account’s included volume is used up, the identification request sent by the snippet returns HTTP 402 until the billing cycle resets or you change plan. The Billing page has the details. History and profile reads keep working.
  • Infrastructure rate limits protect the gateways. During a per-IP ban, identifications carry the marker value 999 in place of a Risk Score; treat any value above 100 as that marker.

​
Conventions

  • Responses are JSON. Error bodies are not uniform, so branch on the HTTP status code rather than parsing a body field. The Errors page enumerates each case.
  • Timestamps are ISO 8601 UTC on webhooks and the Management API; the History API created_at may use YYYY-MM-DD HH:MM:SS instead of ISO 8601.
  • Identifiers (request_id, device_id, visitor_id, session_id, cookie_id) are UUIDs. user_hid is the hashed User HID you pass for a signed-in account, a free-form string, and "anonymous" on anonymous checks.

​
Next steps

Identification Flow

How an identification is scored, reaches your backend, and leads to the account behind it.

Webhooks

The flat webhook payload, X-Shield-Signature verification, and delivery guarantees.

Server API

The History API, the account read, and the Management API profile.

Data Models

Every object the API returns, and the user, device, visitor or IP each identifier maps to.