> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shieldlabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration glossary

> Understand ShieldLabs snippet setup, domain statuses, API keys, webhooks, Event IDs, signatures, client identity and MCP.

Terms for installing ShieldLabs and reading results on your server. Entities, identification fields and risk signals stay in the [glossary](https://docs.shieldlabs.ai/glossary.md).

The [snippet install guide](https://docs.shieldlabs.ai/setup/snippet.md) and the [API overview](https://docs.shieldlabs.ai/api/overview.md) 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](https://docs.shieldlabs.ai/setup/snippet.md).

### 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](https://docs.shieldlabs.ai/api/sdks.md).

### 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](https://docs.shieldlabs.ai/setup/optimizing-usage.md).

### 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](https://docs.shieldlabs.ai/setup/snippet.md#the-four-exports).

## Server results

### Server API

The [server-side API](https://docs.shieldlabs.ai/api/server-api.md): 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](https://docs.shieldlabs.ai/api/models.md#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](https://docs.shieldlabs.ai/api/history.md#pagination).

### Domain id

The public UUID from [Domain](https://docs.shieldlabs.ai/api/history-domain.md). 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**.

| Status | Meaning |
| - | - |
| **Reporting** | At least one check has been saved for the domain. It remains Reporting even if no recent checks have arrived; the time of the last check appears below it. The status does not depend on the selected period's check count. |
| **Pending** | The domain has been added, but no check has been saved yet. The first saved check changes it to Reporting. |
| **Paused** | The domain is paused and new checks do not run. Keys, subdomain settings and webhook endpoints are preserved, as is identification history. History API reads using the domain's key are also rejected. |
| **Frozen** | A temporary automatic restriction after the domain reaches its request-rate limit for ten consecutive seconds. Calls receive HTTP 429 and consume no identifications. It clears after ten consecutive seconds below the limit. |
| **Unavailable** | Domain check data is currently unavailable. This is different from Pending: it does not establish that no first check has arrived. |

Paused takes display priority if the domain is both paused and at its rate limit. See [Integration](https://docs.shieldlabs.ai/dashboard/integration.md) and [Rate limits](https://docs.shieldlabs.ai/rate-limits.md).

## 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](https://docs.shieldlabs.ai/setup/keys.md).

### Private API Key

The per-domain `sec_…` key used on your backend to authenticate the [History API](https://docs.shieldlabs.ai/api/server-api.md) 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](#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](https://docs.shieldlabs.ai/api/webhooks.md#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](#event-id) to deduplicate processing. Webhook HMAC uses a shared secret; [digital signatures](#digital-signature) 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](https://docs.shieldlabs.ai/api/webhooks.md#envelope).

### 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](https://docs.shieldlabs.ai/api/versions.md).

### Timestamps

Timestamps describe different moments, even within one event:

| Field | Meaning |
| - | - |
| Envelope `created_at` | When the notification was created |
| Identification `observed_at` | When the identification was observed |
| Group `evaluated_at` | When the multi-account group was evaluated |
| History `created_at` | The stored identification's observation time |

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](#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](https://docs.shieldlabs.ai/api/webhooks.md#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](https://docs.shieldlabs.ai/glossary.md#high-risk-events) defines the four High-Risk Events themselves.

| Field | Where it appears |
| - | - |
| `kind` | `hre.multi_account.changed`: `data.kind` |
| `revision` | `hre.multi_account.changed`: `data.revision` |
| `level` | `hre.multi_account.changed`: `data.level`; `identification.scored`: `data.hre.account_sharing.level`, `data.hre.account_takeover.level`, `data.hre.impossible_travel.level` |

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](https://docs.shieldlabs.ai/api/webhook-identification.md#high-risk-events).

### 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](#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:

| Value | Meaning |
| - | - |
| `evaluated` | The evaluation completed. A null `level` on a scored High-Risk Event result means no active detection was returned. |
| `not_evaluated` | No completed verdict is available, for example because history was insufficient. |
| `not_applicable` | There is no tracked account for this check. |

A multi-account change event has `status: "evaluated"`; its [action](#action) describes the group transition. Client identity also has assessment statuses, with [different values and meanings](#identity-assessment).

### 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](https://docs.shieldlabs.ai/glossary.md#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](https://docs.shieldlabs.ai/api/webhook-identification.md#account-sharing-counts).

## Multi-account group changes

See the [multi-account event reference](https://docs.shieldlabs.ai/api/webhook-multi-account.md) 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:

| Field | Meaning |
| - | - |
| `user_hids` | Complete sorted list of accounts in the reported group |
| `users_count` | Number of entries in `user_hids` |
| `added_user_hids` | Accounts added by this transition; a new detection lists all members |
| `removed_user_hids` | Accounts removed by this transition; a resolution lists the former members |
| `members_complete` | Whether the supplied member list is complete |

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:

| Field | Meaning |
| - | - |
| `publication_epoch` | Scope of the publication sequence; keep it with the site and cluster when tracking revisions |
| `publication_version` | Identifier of the publication containing the result, preserved as a decimal string |
| `coverage_id` | Opaque identifier for the associated evidence coverage; retain it for correlation |

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](https://docs.shieldlabs.ai/api/webhook-identification.md#client-identity).

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.

| Field | Signal |
| - | - |
| `search_bot_owner` | `search_bot` |
| `ai_bot_owner` | `ai_bot` |
| `ai_browser_owner` | `ai_browser` |

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.

| Field | Meaning |
| - | - |
| `profile_id` | Identifier of the recognized profile |
| `provider_id`, `provider_name` | Provider identifier and display name |
| `agent_name` | Recognized agent or client name |
| `client_kind` | Client category: `browser`, `crawler` or `fetcher` |
| `purpose` | The profile's stated function |
| `source` | Where the recognized claim came from |

`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:

| Value | Meaning |
| - | - |
| `search` | Content collection for search |
| `training` | Content collection for model training |
| `user_fetch` | Content retrieval for a user request |
| `unknown` | No more specific purpose is assigned to the profile |

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:

| Value | Meaning |
| - | - |
| `http_ua` | User-Agent header |
| `client_hint` | Browser client hint |
| `header_hint` | Another client identity header |
| `published_ip` | Published provider IP information |

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.

| `status` | Meaning |
| - | - |
| `verified` | Available evidence supports the assessed attribution |
| `unverified` | The recognized claim has not been verified |
| `unknown` | The assessment does not establish the attribution |
| `conflict` | Identity claims or verification evidence disagree |

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](https://docs.shieldlabs.ai/features/ai-assistants.md#interpret-identity-assessments).

### Verification evidence

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

| Field | Meaning |
| - | - |
| `id` | Evidence identifier, referenced by `evidence_ids` |
| `method` | Verification method used |
| `source_id`, `source_revision` | Evidence source and its version |
| `checked_at` | When that evidence source was checked |
| `evaluated_at` | When the evidence was evaluated for this result |
| `covered_attributes` | Identity attributes covered by the evidence |
| `covered_components` | Optional list of signed request components covered by signature evidence |
| `request_binding` | Optional value associating signature evidence with the request being checked |
| `replay_policy` | Optional label for the replay-check policy applied to signature evidence |

### 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](#hmac) with a shared secret. See [AI-agent identity verification](https://docs.shieldlabs.ai/features/ai-agents.md#how-shieldlabs-verifies-ai-agent-traffic).

### Verification method

The `client_identity.evidence[].method` field names the kind of evidence check:

| Value | Meaning |
| - | - |
| `published_ip` | Attribution using published provider IP ranges |
| `fcrdns` | Provider attribution using forward-confirmed reverse DNS |
| `http_signature` | Verification of an HTTP request signature |

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:

| Field | Meaning |
| - | - |
| `schema_version` | Version of the client identity object's format |
| `classification_revision` | Revision of the classification result |
| `classifier_version` | Version of the classifier that produced the result |
| `registry_revision` | Version of the recognized-profile registry |
| `observed_at` | When the client activity was observed |
| `decided_at` | When the classification decision was made |

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](https://docs.shieldlabs.ai/setup/mcp.md).

### 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](https://docs.shieldlabs.ai/setup/mcp.md#investigation-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](https://docs.shieldlabs.ai/billing.md).

### 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](https://docs.shieldlabs.ai/rate-limits.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.