Skip to main content
Terms for installing ShieldLabs and reading results on your server. Entities, identification fields and risk signals stay in the glossary. The snippet install guide and the API overview cover the same concepts in full.

Browser integration

Snippet

The snippet is a JavaScript module you add to your site. It collects device, browser and network characteristics and sends them to ShieldLabs for a check. Use the module loaded from the ShieldLabs CDN. For the selected domain, Install the snippet provides two ready-made examples: Anonymous visitors and Authenticated users. The load URL already contains that domain’s Public Key. A separate call starts the check. Repeated regular calls for the same user in the same browser are subject to a five-minute pause. Each created check consumes one identification from the plan’s included volume. See Install the snippet.

SDK

A software development kit for integrating ShieldLabs. Browser SDKs start identifications and return their Identification IDs. Server SDKs read results and provide helpers for processing them. See SDKs.

Cooldown

The same-user visit window that suppresses repeat regular snippet checks. A suppressed call creates no identification and consumes no identification quota. See Visit and cooldown behavior.

Force check

An explicit identification that bypasses the regular-check cooldown. It creates a fresh Identification ID, consumes one identification when admitted and restarts the cooldown. It does not create a new Session ID. See Snippet methods.

Server results

Server API

The server-side API: the History API on account.shieldlabs.ai (Private API Key), which reads your identifications.

Snapshot

A stored identification. A History identification card returns its id, identifiers, risk.score and risk.band when risk.state is ok, signal names in signals.items and attribution in traffic. See History card.

Pagination

Reading a result list in smaller pages. In History, limit is the page size and page_token continues from next_page_token. data contains the rows for this page. See History pagination.

Domain id

The public UUID from Domain. History paths use it as {domain_id}. It is not the hostname.

Domains

Domain status

Domain status is the single status shown in the Status column under Integration > Domains. Paused takes display priority if the domain is both paused and at its rate limit. See Integration and Rate limits.

API keys

Public Key

Public Key is the public key for a connected domain. The snippet’s load URL passes it as publicKey, associating the check with that domain. Integration > API keys shows a separate key for each domain, with its full value visible. The key is intentionally visible in page code. A request is accepted only when the key belongs to the open page’s domain. Subdomain checks are accepted when the connected domain allows subdomain traffic. Using the key in a snippet on another domain does not let that domain submit checks on its behalf. Public Key does not grant access to saved checks and is not used to verify webhook signatures. Rotate immediately replaces the key, and the previous value stops being accepted. Update the snippet’s load URL with the new key. See API keys.

Private API Key

The per-domain sec_… 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.

Secret Key

The per-domain server credential. Never ship it to the browser. Webhooks use separate whsec_… signing secrets per endpoint.

Webhooks

Webhook

A webhook is a signed notification ShieldLabs sends as an HTTP POST request to a configured HTTPS endpoint in your application. The signature lets your server verify its authenticity and integrity. ShieldLabs automatically sends the result once it is ready, without requiring a separate History read. Identifications are saved even if no endpoint is configured. identification.scored delivers one check’s Risk Score, signals, detection flags and identifiers. The same notification can include results for three account-event types: Account sharing, Impossible travel and Account takeover. A result can also mean that no event was detected. Multi-account group changes arrive separately in hre.multi_account.changed, which must be enabled. The webhook.ping connectivity check does not create a visitor identification. You can configure up to 10 endpoints for one domain. Each has its own signing secret. Delivery can repeat, and notifications can arrive out of order. Retry attempts are bounded. Recognize repeated deliveries using event_id; use revision to order multi-account group changes. If an identification notification is missed, read that check in History. History cannot reconstruct a missed group change.

Webhook signing secret

The whsec_… 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.

HMAC

A hash-based message authentication code: a value calculated from a message and a shared secret. ShieldLabs uses HMAC-SHA256 to authenticate webhook bodies. Your backend calculates the value from the received raw body and the endpoint’s signing secret, then compares it with X-Shield-Signature. A match confirms that the body has not changed and was authenticated with that secret. HMAC does not encrypt the body. See Webhook verification.

Webhook signature

The HMAC value ShieldLabs sends in X-Shield-Signature. Verify it before trusting or processing the event; a request that contains ShieldLabs-looking JSON is not proof of its source. Use the exact received bytes and keep the signing secret on your backend. A valid signature does not prevent duplicate delivery: use the Event ID to deduplicate processing. Webhook HMAC uses a shared secret; digital signatures use a key pair.

Event ID

Event ID is the identifier of one ShieldLabs notification, returned in event_id. Use it to recognize a repeated delivery: the value stays the same on retries, including delivery to different endpoints. The receiver uses it to skip messages it has already processed and avoid repeating an associated action, such as awarding a bonus twice. Identification ID belongs to a check. Event ID belongs to the notification of that check’s result, or to a separate notification about a multi-account group change. Use revision to order group changes. Running a test send again can reuse the previous Identification ID but produces a new Event ID. A retry of the same test notification preserves event_id. The X-Shield-Event-Id header repeats the notification identifier. Deduplicate using the event_id in the request body after successfully verifying its signature.

Webhook envelope

The outer object containing the event’s identity, type, version and creation time. Its data field contains the result specific to that event. A connectivity ping has no data. See Envelope fields.

Event type

The event_type field tells you which notification was sent: identification.scored for a completed identification, hre.multi_account.changed for a multi-account group change, or webhook.ping for a connectivity check. Use it together with schema_version to choose how to read data.

Site ID

The numeric site_id identifies the registered site to which an event belongs. The domain hostname and the Site ID refer to the site’s scope in different forms. Keep site scope when associating event IDs, groups and revisions.

Event data

The data object inside a webhook envelope. Its fields depend on event_type. In History, data holds an array of cards for a list response or one card object for a single-record response.

Schema version

The schema_version of a webhook body. Read it together with event_type to select the matching event model. It is separate from the installed SDK package version. See Versions and availability.

Timestamps

Timestamps describe different moments, even within one event: Webhook timestamps use RFC 3339, for example 2026-10-27T09:00:00Z. Z means UTC. A History timestamp may use YYYY-MM-DD HH:mm:ss. Creation time alone does not order group changes; use revision.

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.

X-Shield-Event-Id

A convenience header containing the event’s ID. Verify the signature, then use the event_id in the verified body to deduplicate deliveries.

Raw body

The exact bytes received by your webhook endpoint, before JSON parsing or formatting. Signature verification uses these bytes. Parsing and re-serializing the object can change the body and invalidate the signature.

Idempotency

Processing a repeated input without repeating its effect. Deduplicate webhook delivery by event_id; atomically bind accepted identifications to protected business actions. Group state also requires revision ordering.

Retry

Another attempt to deliver the same event after a failed delivery. Retries preserve the logical Event ID. Delivery attempts are bounded, and distinct events can arrive out of order. See Delivery guarantees.

Optional and null fields

An optional field can be absent from JSON. A field with null is present without a value; an empty string, an empty array and false are other distinct values. Interpret them according to the field’s contract. For example, a High-Risk Event result’s null level must be read together with status.

Account-event results

These terms describe the High-Risk Event results in scored webhooks and the separate multi-account group event. The product glossary defines the four High-Risk Events themselves. The scored-identification data object has no group kind or group revision. Its account-event levels are nested inside hre.

High-Risk Event results

In a scored webhook, hre contains the separate account_sharing, account_takeover and impossible_travel evaluations. Multi-accounting is delivered through hre.multi_account.changed. See High-Risk Event fields.

Kind

The kind field names the detection represented by a multi-account group result. In hre.multi_account.changed, data.kind is multi_account. The envelope’s event_type names the notification; kind describes the detection inside its data. It is separate from the client_kind used for bot and AI attribution.

Level

The level field is the confidence of an account-event detection: medium or high. It is separate from the numeric Risk Score and the Trusted, Suspicious or Dangerous risk categories. A scored webhook’s data.hre.*.level can be null; read the corresponding status to understand why. A resolved multi-account group’s data.level is null.

Status

The status field tells you whether an account-event evaluation was completed: A multi-account change event has status: "evaluated"; its action describes the group transition. Client identity also has assessment statuses, with different values and meanings.

Reason

The reason field gives context for an evaluation or identity assessment. It can be empty. Preserve unrecognized reason values; they are not a replacement for status or level.

Cluster ID

The cluster_id identifies a group of related accounts or observations. Multi-account updates use it to refer to the same group. In a scored High-Risk Event result, it can be null when no cluster reference is supplied. See Cluster ID.

Account-sharing counts

The account-sharing result can provide devices, the reported device count, and min_devices, the minimum used for that evaluation. When devices_at_least is true, devices is a lower bound: 4 means at least four. Read these values as returned. See Account-sharing counts.

Multi-account group changes

See the multi-account event reference for the complete payload.

Action

The action field describes what changed in a group: detected starts an active episode, updated changes an existing group’s members, confidence or rules, and resolved ends the reported active episode. A resolution does not establish that every former member is safe.

Detected

The boolean detected reports whether the group is active in this transition. It is true for an active detection or update and false for a resolution. It is separate from the field action, which names the change.

Revision

The revision field is the version of a change to one multi-account group. A later revision represents a newer group state. It is a decimal string so large integers retain their precision. Compare revisions numerically, for example with JavaScript BigInt, within the same site, publication epoch and cluster. An Event ID handles repeat delivery; a revision orders different changes.

Previous revision

The previous_revision field refers to the group’s preceding transition while it was active. It is null for a new active episode. A null value does not mean the current revision is missing.

Rules version

The rules_version field identifies the evaluation rules used for a result. Store it as returned. It is separate from the event’s schema version and the group’s revision; it is not a setting to configure your own detection thresholds.

Group members

Account identifiers in a multi-account group use the same pseudonymous User HIDs as your integration: For a resolution, user_hids identifies the group being resolved. Member-list completeness and evidence-detail completeness are separate.

Publication source

The group’s source object identifies the result publication and its evidence coverage: These identifiers provide context for a received result. They do not add points to a Risk Score.

Evidence summary

The group’s evidence_summary describes the evidence accompanying the result. basis_types names the types of evidence, rules contains the reported rule labels, and detail_truncated indicates whether detailed evidence was shortened. A shortened evidence summary does not make the user_hids member list partial.

Client identity and bot attribution

The optional client_identity object describes recognized client claims and the evidence that supports an attribution. It can appear in scored webhook data and stored History results. See Client identity fields. The webhook path is data.client_identity. Its fields can be absent or null; arrays can be empty. Missing metadata does not establish that the visitor is human or that identity verification succeeded. Preserve unfamiliar fields and string values when processing a result.

Bot provider

Bot owner is the company behind a recognized search bot, AI bot or AI browser. Use it to understand which companies are represented in this traffic and group results by provider. Each type has its own field: search_bot_owner, ai_bot_owner or ai_browser_owner. Each field contains one company name and is sent with the corresponding signal only when the provider is known. The value names a company, rather than a program, for example Google, OpenAI or Browserbase. It does not identify the person controlling the client. These fields do not change the Risk Score. In identification.scored, these fields are inside data. The webhook does not send the string Unknown. The dashboard displays the name beside a signal in the Good bot group. When no name is available, the card may display Unknown.

Availability

The client_identity.availability field reports whether input for identity classification was available: available or input_unavailable. Available input does not establish verified attribution.

Identity claim

An entry in client_identity.claims describing a recognized client profile. A claim names the client as presented; it does not by itself prove the identity. browser describes a browser platform, crawler a client collecting or indexing content, and fetcher a client retrieving pages for a request. These are identity categories, separate from the ai_bot, ai_browser and search_bot detection flags.

Client purpose

The client_identity.claims[].purpose field describes the recognized profile’s function: Purpose describes the recognized profile, not proof of the intent of every request. An unknown purpose is separate from an unavailable provider name or an unknown identity assessment.

Claim source

The client_identity.claims[].source field identifies the information used to recognize a profile: Read verified for the attribution supported by evidence. A source label alone does not verify every identity attribute.

Verified attribution

An entry in client_identity.verified connecting an identity attribute to supporting evidence. subject names the attribute being verified, value_id identifies its value, and evidence_ids references entries in the evidence array. Verification of a provider does not automatically verify a specific agent name. subject: "provider" establishes provider attribution; "infrastructure" establishes a browser platform. An empty verified array contains no verified attribution to rely on.

Identity assessment

The client_identity.assessments array reports identity assessment results. In a scored webhook, its full path is data.client_identity.assessments. Each entry has a status and a reason; the optional candidate_profile_id matches the profile_id of a claim. An entry without a candidate profile reports a general assessment, rather than the verdict for a particular named client. More than one assessment can accompany a result. Read the verified attribute and its evidence before assuming the whole client identity is verified. An empty assessment array means no assessment entries were supplied; it does not establish a verified identity or a human visitor. An identity assessment is separate from the Risk Score and the account-event level. See Interpret identity assessments.

Verification evidence

An entry in client_identity.evidence records what supports a verified attribution:

Digital signature

A cryptographic signature created with a private key and verified with the corresponding public key. It can establish who signed a message and whether the signed content changed. For supported AI browser platforms, ShieldLabs verifies signed requests as evidence of the platform’s identity. Read the verified attributes and evidence to understand what was confirmed; platform verification does not identify the person controlling it. ShieldLabs webhook verification instead uses HMAC with a shared secret. See AI-agent identity verification.

Verification method

The client_identity.evidence[].method field names the kind of evidence check: The verified scope is listed in covered_attributes and the corresponding verified entry. A method name alone does not establish a particular provider or agent. For signature evidence, replay_policy: "time_window" describes time-window-based replay checking; retain request_binding as the opaque request reference returned with the evidence.

Identity result versions and times

Metadata inside client_identity identifies the returned classification: Store these values as received. Their scope is the client identity object; do not use them to order multi-account group changes.

AI tools

MCP

Model Context Protocol: the interface an AI client uses to discover and call ShieldLabs tools. Use it to investigate identifications and, when exposed by the connection, manage domains and webhooks. See Connect an AI client.

OAuth

The sign-in and authorization flow used by the ShieldLabs MCP connection. You sign in to ShieldLabs and authorize the client; the client manages access tokens.

Access token

The credential an authorized AI client uses for its MCP connection. Your client manages it after OAuth sign-in. It is separate from the Public Key, Private API Key and Management Secret Key used by other integrations.

MCP tool

A named operation exposed by the connected ShieldLabs MCP server. The client discovers its input fields and can call it to read results or manage supported resources. Use the tool list from your connection; see MCP tools.

Usage

Included volume

The number of identifications your plan includes: 5,000 one time on Free, and a set volume per billing cycle on paid plans, shared by all your domains. History reads, webhooks, the analytics dashboard and exports are free. At the included volume the identification request returns HTTP 402 until the billing cycle resets or you change plan; on Free, until you change plan. See Billing.

RPS

Requests per second, the unit used for a request-rate limit. It describes how quickly requests can be sent; included identification volume describes how many identifications the account has available. See Rate limits.