Users, devices, visitors and IPs
ShieldLabs works with five identities, each with its own risk and its own links: users, devices, visitors, public IPs and local IPs. Users, devices, visitors and IPs covers the model, and Identifiers covers how each identifier is built and how long it lasts.Identification
One check by the snippet, run when you callcheckAnonymous, checkAuthenticatedUser or a forceCheck* variant. Each identification carries one visitor, one device and one public IP, and at most one user and one local IP. It returns a Risk Score with its named risk signals and is the unit your plan counts. Identifications are the event layer under your users, devices, visitors and IPs.
Identity
One of the five things ShieldLabs tracks with its own risk and its own links: a user, a device, a visitor, a public IP or a local IP.User HID
Your account, keyed by the hashed or pseudonymous id you pass withcheckAuthenticatedUser, never a raw email or login. Users, account-level risk and all four High-Risk Events are built on it. Anonymous checks send "anonymous". Webhook and History key: user_hid.
Device ID
The durable device, computed on the server from the device itself. It holds through cleared cookies, incognito mode and IP changes; another browser is another Device ID. An all-zero Device ID (00000000-0000-0000-0000-000000000000) means no usable device signals reached ShieldLabs for that identification; the rate-limit marker (Risk Score 999) is one such case. Route it to review rather than allowing it. Key: device_id.
Visitor ID
One device plus one cookie, computed on the server from the Device ID and the Cookie ID. It changes when cookies or storage are cleared, so one Device ID can have many Visitor IDs. Key:visitor_id.
Public IP
The public address of an identification, with its country. Webhook:public_ip (ip, country); History search type ip.
Local IP
The address the browser itself reports, which can differ from the public IP behind a VPN or proxy. Webhook:local_ip (ip, country); local_ip.ip is empty when it was not captured. The History API has no Local IP search, so keep local_ip.ip from each webhook to group by it. Compare its country with the public IP’s (see IP Mismatch).
Linked identities
The other identities an identity shares identifications with: a user’s devices, visitors, public IPs and local IPs, or the accounts seen on one device or IP. In code, read them with History lookups byuser_hid, device_id, visitor_id or ip. In the analytics dashboard, each user, device, visitor and public IP has a card with its band for the selected period and its linked identities; local IPs appear on those cards as linked local IPs, with the identifications behind each. See User, device, visitor and IP cards.
Analytics dashboard
The ShieldLabs screens where you manage domains, keys, webhooks and your plan, and review your traffic, your users and their High-Risk Events. It has Overview, Analytics, AI Copilot, Integration, Usage and Support, with Settings in the account menu. Start at Overview.Per-call identifiers
Request ID
A UUID generated per identification. It is the join key that ties a single check across the webhook and the History API. Use it as your idempotency key. Key:request_id.
Session ID
A UUID for one browsing session, written by the snippet tolocalStorage and shared by the open tabs of your site (legacy sessionStorage keys are migrated on first read). A new Session ID starts on the next page load after the last open page of your site is closed or navigated away from. Key: session_id.
Cookie ID
A first-party cookie andlocalStorage UUID generated in the browser. It is lost when cookies or storage are cleared, which also gives the device a new Visitor ID. Key: cookie_id.
Risk Score and risk signals
The Risk Score reference and the risk signal catalog explain the mechanics behind the terms below.Risk Score
The score from 0 to 100 on each identification: the sum of the weights of the risk signals that fired, capped at 100. Higher means riskier. Every risk signal behind it comes back by name with its weight. The one value above 100 is999, the rate-limit marker. Users, devices, visitors and IPs carry a band word instead of a number (see Band).
Band
The three labels the Risk Score maps to: Trusted (0 to 29), Suspicious (30 to 59), Dangerous (60 to 100). The webhook and the History API return only the number, so you map it to a band. A user, device, visitor or IP takes the worst band of its identifications: only an identification has a number. The Risk Score page carries the full table.Risk signal
A detection that adds weight to the Risk Score of an identification, such as VPN, Tor, OS Mismatch or Anti-detect Browser. ShieldLabs collects 300+ device and network signals on each identification and cross-checks them; risk signals are the detections that carry a weight. The full catalog and its weights are on Risk Signals.score_details
The breakdown of the Risk Score on a History API row: a JSON string with one{ "Value", "Description" } entry per detail. The webhook carries the same breakdown as data.signals, stable { "name", "weight" } slugs; branch on those. See Data Models.
Detection flags
Thedetection_flags object inside webhook data: 19 stable booleans, one per detection (for example vpn, tor, datacenter_ip, abuser). Branch on these and on signals[].name slugs in your code. Five flags are informational and carry no weight: incognito, ip_mismatch, search_bot, suspicious_paid_click and check_incomplete. History API rows carry most of the same detections as is_* booleans. The full list is in the webhook reference.
Risk signals and connections
The risk signals reference covers the checks and connection types defined below.Masking detection
The checks that find how a user hides: VPN, proxy, Tor, Privacy Relay, datacenter IPs, IP reputation, anti-detect browsers, and location or timezone spoofing.Connection type
The classification of an identification’s connection. Theconnection_type field on the webhook carries one of direct, mobile, vpn, proxy, tor, privacy_relay, browser_vpn_proxy, or unknown (when the type could not be resolved).
Where an entry below has a stable boolean in detection_flags, the flag name is shown in code so you can map a log field to its meaning.
VPN
A virtual private network routes traffic through an intermediary server, so the visible IP belongs to the VPN provider rather than the user (vpn).
Browser VPN/Proxy
An in-browser VPN or proxy extension routing the session, rather than a system-wide VPN. An extension-level mask and a deliberate choice to hide the connection (browser_vpn_proxy).
Proxy
A proxy server relays a connection so the destination sees the proxy’s IP instead of the user’s. Proxies range from datacenter to residential; ShieldLabs weighs the proxy signal together with IP reputation and datacenter checks (proxy).
Residential proxy
A proxy that routes traffic through real consumer devices and home ISPs, so the exit IP looks like an ordinary residential connection and carries residential reputation. Read it together with the user’s other devices and IPs, not on the IP alone. For example, a residential proxy paired with an anti-detect browser is a far stronger signal than the IP by itself.Datacenter IP
An IP that belongs to a hosting provider or cloud datacenter rather than a consumer ISP. Real users rarely browse from datacenter ranges, so ShieldLabs treats it as a risk signal (datacenter_ip).
Tor
The Tor network routes traffic through a chain of volunteer relays, so the exit IP cannot be traced back to the user. A known Tor exit node is the strongest single risk signal (tor).
Privacy Relay
iCloud Private Relay or a similar service that hides the IP for privacy. ShieldLabs surfaces it as its own connection type so you can choose to treat a privacy-conscious user differently from a generic VPN (privacy_relay).
Abuser Flag (IP reputation)
A reputation check on the IP or device. It flags addresses that appear on known blocklists, for example a known proxy or Tor exit, or an address linked to earlier spam or network abuse (abuser).
Anti-detect browser
A browser built to spoof or randomize its fingerprint to evade identification. ShieldLabs surfaces it through cross-layer signals. A deliberate, sophisticated evasion attempt and a strong tell (signals[].name antidetect_browser, flag anti_detect_browser).
Anti-detect browser, proxy-routed
An anti-detect browser whose traffic is routed through a proxy (signals[].name proxy_routed_antidetect, weight 60). It has no detection_flags key; the anti_detect_browser flag covers the direct case.
Browser automation
A browser driven by an automation framework instead of a person: a bad bot. Near-certain non-human traffic; it scores independently of the connection (browser_automation, weight 60).
Search bot
A known search-engine crawler such as Googlebot or Bingbot: a good bot. ShieldLabs sets its Risk Score to 0 and puts it in the Search bot traffic channel, so crawlers stay out of your risk numbers (search_bot, informational flag).
Bots
Good bots are known search-engine crawlers (search_bot, Risk Score set to 0). Bad bots are automated browsers (browser_automation, weight 60). Headless and automated clients also raise javascript_disabled (weight 90). The analytics dashboard counts good bots and bad bots per unique visitor. See Bots and automation.
OS Mismatch
The operating system reported by the device and browser does not match the OS determined from other data, such as the network. A clear spoofing sign: an honest device does not contradict itself (os_mismatch).
OS not Detected
The operating system could not be determined from the available device, browser, and network data. The environment was stripped down or had unusual parameters (os_not_detected).
Timezone Mismatch
The browser’s timezone does not match the timezone of the IP’s location. A location-spoofing tell that can also be innocent, such as a traveler (timezone_mismatch).
IP Mismatch
The public IP (public_ip) and the local IP (local_ip) are different addresses. Informational only: it does not add to the Risk Score. A difference can be ordinary on mobile networks, so compare public_ip.country with local_ip.country rather than branching on the flag alone (ip_mismatch).
STUN not checked
The network check did not complete for this identification (stun_not_checked, weight 30). When the check completes late, a stun_late_correction entry with weight −30 takes the weight back out.
Check incomplete
An informational flag: some checks did not finish before the result was sent (check_incomplete). It carries no weight.
JavaScript Disabled
A headless or automated client: one of the strongest risk signals, weight 90 (javascript_disabled).
Incognito
The identification ran in a private or incognito browsing mode. Informational only: it does not add to the Risk Score (incognito).
Suspicious paid click
An informational flag set on an identification on the Google Ads, Meta, TikTok, LinkedIn, X, Pinterest or Microsoft Ads channel (paid or organic) with a Risk Score of 60 or more. A paid-traffic quality marker for Traffic Quality; it carries no weight (suspicious_paid_click).
IP geolocation
The country resolved from an IP address. ShieldLabs returns it as thecountry on both public_ip and local_ip, and uses it for location checks and the IP Mismatch country comparison.
Browser fingerprinting
The technique of recognizing a browser from a combination of its attributes without relying on cookies. It is one component of ShieldLabs Device Intelligence, alongside network analysis and risk signals.Device fingerprinting
Recognizing a device from stable hardware and software characteristics, producing an identifier that holds through cookie clears and new browser sessions. ShieldLabs returns it as the Device ID.Device Intelligence
The discipline of combining a device fingerprint with network analysis, risk signals, and mismatch detection into one profile, returned as a durable Device ID plus the risk signals behind it.Network Intelligence
IP geolocation and reputation, connection type, and the VPN, proxy, Tor, datacenter and Privacy Relay signals. See accuracy.Headless browser
A browser running without a visible interface, driven by automation rather than a person. Headless clients raisejavascript_disabled (weight 90) and automated browsers raise browser_automation (weight 60); see Bots.
High-Risk Events
The High-Risk Events reference covers the events and confidence levels below.High-Risk Event
One of four events ShieldLabs detects directly on your users: Multi-accounting, Account sharing, Impossible travel and Account takeover. Each carries Medium or High confidence, on its own axis, separate from the Risk Score and its bands: a user can be Trusted on every identification and still be multi-accounting. High-Risk Events are available in the analytics dashboard, the API and webhooks. They are built on the User HID, so pass a hashed User HID withcheckAuthenticatedUser on every signed-in page.
Multi-accounting
Several accounts run by one person, linked through the devices and network they share. By default it fires from 3 accounts on one visitor (one device plus one cookie), and the threshold is configurable. Multi-accounting is detected even after cookies are cleared, since the shared devices and network keep the accounts linked.Account sharing
One account used from several distinct devices. By default it fires from 4 devices on one account, and the threshold is configurable.Impossible travel
An account appearing in locations it could not reach in the time between them.Account takeover
An existing account appearing in a new environment that points to someone else using it.Medium / High confidence
The two confidence levels a High-Risk Event carries, Medium and High. The confidence depends on the combination of evidence and sits apart from the Risk Score bands.Analytics
The analytics dashboard reports the metrics below for the period you select.Traffic quality
How risky your traffic is overall in the selected period: the mean Risk Score of the period’s identifications, shown with its band word as the gauge on Overview.Identifications
The number of identifications in the selected period.Unique visitors
The number of distinct Visitor IDs in the selected period. Each is one device plus one cookie, so the count estimates people from devices and cookies.Risky users
Users whose worst band in the period is Suspicious or Dangerous and who have no High-Risk Event.High-Risk Event users
Users with at least one High-Risk Event in the period, in any band.Analytics chart
The trend of identifications, unique visitors, users, devices or public IPs over the selected period, split by band. Its bucket size follows the length of the period.Traffic Source
The acquisition attribution on each identification: the resolved channel, the referrer domain, the landing URL, the paid click ID type (for examplegclid) and the UTM parameters (webhook: traffic_source). History API rows also carry a coarser channel group. The analytics dashboard ranks channels, sources and campaigns by the risk of the traffic they bring.
Channel
The resolved acquisition channel of an identification: Google Ads, Meta, TikTok, LinkedIn, X, Pinterest, Microsoft Ads, Organic Search, Search bot, Referral, Direct or Other. History API rows add a coarser channel group: Paid Search, Paid Social, Social, Organic, Bot, Referral, Direct or Other.UTM parameters
Theutm_source, utm_medium, utm_campaign, utm_content, and utm_term values from the inbound URL, captured on each identification for source attribution and surfaced in the analytics dashboard and exports.
Integration
The snippet install guide and the API overview cover the integration concepts named below.Snippet
The ShieldLabs JavaScript snippet: an ES module loaded fromcdn.shieldlabs.ai that collects signals in the browser and runs an identification when you call checkAnonymous, checkAuthenticatedUser or a forceCheck* variant.
Public Key
The per-domain key placed in the snippet URL. It identifies the domain and is safe to expose in the browser.Secret Key
The per-domain key used only on your backend to authenticate the Management API. Never ship it to the browser. Webhooks use separatewhsec_… signing secrets per endpoint.
Private API Key
The per-domainsec_… key used on your backend to authenticate the History API on account.shieldlabs.ai. Sent as a Bearer token; never expose it in the browser.
Webhook signing secret
Thewhsec_… value for one webhook endpoint. It keys the HMAC in the X-Shield-Signature header. Copy it from your endpoint in the analytics dashboard under Integration > Webhooks; one secret per endpoint.
Webhook
The server-to-server delivery of an identification’s result to an endpoint you register in the analytics dashboard. One webhook is sent per identification: in about 300 ms, or at most about 10 seconds after the check when follow-up network checks run. The body is a signed envelope (event_type, schema_version, created_at, data). Delivery is at-most-once with no retries, so make handlers idempotent on data.request_id.
X-Shield-Signature
The request header that carries the webhook HMAC:sha256= plus hex(HMAC-SHA256(key = the endpoint’s whsec_… secret, message = the raw body)). Verify it before trusting the payload.
Idempotency
The property where handling the same result more than once has the same effect as handling it once. Because webhook delivery is at-most-once and you may also read the same result from the History API, key your writes onrequest_id so a webhook and a History read for one check never double-apply.
Server API
The server-side APIs: the History API onaccount.shieldlabs.ai (Private API Key), which reads your identifications, and the Management API on api.shieldlabs.ai (Secret Key), which reads your profile and the remaining included volume on your account.
History API
TheGET /api/v1/history/{search_type}/{value} endpoint on account.shieldlabs.ai. It returns stored identifications by one of seven keys: ip, user_hid, visitor_id, device_id, request_id, session_id or cookie_id. Read everything one account did with user_hid/{value}, paged with limit and offset. It is the guaranteed read when a webhook may have been missed, and reads are free.
Snapshot
A stored record of one identification, returned by the History API. It carries the same identifiers as the webhook in its own shape:score for the Risk Score, score_details for the breakdown and is_* booleans for the flags, plus connection and network fields.