# Noxtica documentation (full text)

> Every page of https://noxtica.com/docs/ as clean Markdown, in the order an integration follows it: install, consent, protected actions, backend verification, identity verification, webhooks, API reference, MCP, then the remaining topics. Each page starts after a `---` line with its canonical URL.

The generated per-operation API reference (10 pages under https://noxtica.com/docs/api/reference/) is not repeated here: read https://noxtica.com/docs/api/openapi.json, or fetch one area page as https://noxtica.com/docs/api/reference/<area>/index.md. The page index is https://noxtica.com/llms.txt.

---

Source: https://noxtica.com/docs/
Markdown: https://noxtica.com/docs/index.md
Last updated: 2026-10-24

# Noxtica Documentation

Use these docs to move from an activated account to a measured, reviewable policy. Noxtica provides browser and device intelligence, calibrated risk, bot and agent controls, and operator workflows; your team chooses where those outputs influence a customer journey.

Availability is account-specific. Backoffice visibility, API scopes, module status, and your service agreement determine which surfaces you can use. A capability described in the directory may still require entitlement, tenant or domain activation, a supported client, or privacy/legal review.

## Choose a path by task

| I need to…                                       | Start here                                                                                  | Then use                                                                                                                     |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Install the browser collector                    | [Install & Browser Runtime](https://noxtica.com/docs/browser-runtime/)                                         | [Getting Started](https://noxtica.com/docs/getting-started/) for the evaluation path and application responsibilities                           |
| Make a trusted backend decision                  | [Backend Integration](https://noxtica.com/docs/backend-integration/)                                           | [Why Calibration, Not Verdicts](https://noxtica.com/docs/why-calibration/) for policy design                                                    |
| Verify a customer identity from my backend       | [Identity verification integration](https://noxtica.com/docs/identity-verification-integration/)               | [KYC Hosted Sessions](https://noxtica.com/docs/kyc-hosted-sessions/) for session lifetime and expiry                                            |
| Call a server API from my backend                | [API overview](https://noxtica.com/docs/api/)                                                                  | [Authentication](https://noxtica.com/docs/api/authentication/), [Webhooks](https://noxtica.com/docs/api/webhooks/) and the [API reference](https://noxtica.com/docs/api/reference/)  |
| Give an AI agent the docs or the API             | [Integrate with an AI agent](https://noxtica.com/docs/ai-agents/)                                              | The [OpenAPI files](https://noxtica.com/docs/api/openapi.json), [`/llms.txt`](https://noxtica.com/llms.txt) and the Markdown version of every page                |
| Understand a score or reason                     | [Detection Signals](https://noxtica.com/docs/detection-signals/)                                               | [Threat Categories](https://noxtica.com/docs/threat-categories/) and the fingerprint detail in Backoffice                                       |
| Roll out challenge or block actions              | [Use Cases](https://noxtica.com/docs/use-cases/)                                                               | [Engineering Principles](https://noxtica.com/docs/principles/) for shadow-first and low-confidence handling                                     |
| Investigate related activity                     | [Capability Reference → Account linking](https://noxtica.com/docs/features/#account-linking-and-investigation) | Compare, investigation, analytics, and eligible export surfaces in Backoffice                                                |
| Govern automated agents                          | [Capability Reference → Agent identity](https://noxtica.com/docs/features/#agent-identity-and-control)         | [Agentic Security](https://noxtica.com/docs/concepts/agentic-security/) and [Know Your Agent](https://noxtica.com/docs/concepts/know-your-agent/)                  |
| Connect an AI agent or use the console assistant | [Capability Reference → AI operations](https://noxtica.com/docs/features/#ai-assisted-operations)              | [MCP Integration](https://noxtica.com/docs/concepts/mcp-integration/) or [AI Assistant](https://noxtica.com/docs/concepts/ai-assistant/)                           |
| Review privacy and operating boundaries          | [Engineering Principles](https://noxtica.com/docs/principles/)                                                 | [Capability Reference → Governance](https://noxtica.com/docs/features/#governance-and-data-controls) plus your contract and current legal pages |
| See everything customers can use                 | [Customer Capability Reference](https://noxtica.com/docs/features/)                                            | Follow any of the twelve family anchors to configuration, outputs, value, eligibility, and limits                            |
| See what changed in a collector release          | [SDK Changelog](https://noxtica.com/docs/changelog/)                                                           | [Install & Browser Runtime](https://noxtica.com/docs/browser-runtime/) for consent modes, events and the command queue                          |

## What is Noxtica?

Noxtica collects eligible browser, device, network, and interaction context, checks the available evidence for consistency, and returns a calibrated assessment. A result can help you recognize a returning browser installation, identify suspicious automation or infrastructure, verify supported agent identities, prioritize an investigation, or apply a route-specific policy.

The result is not proof that a visitor is a particular person, a guaranteed bot verdict, or a replacement for authentication. Read risk, confidence, and reasons together and combine them with the value and reversibility of the action your application is considering.

### Key Capabilities

- **Device and browser intelligence:** receive a tenant-scoped device handle and a calibrated assessment from an activated collector.
- **Bot, abuse, and network defense:** combine automation, consistency, infrastructure, and interaction reason families without making one signal decisive.
- **Risk and decisioning:** use score, five-level risk tier, confidence, and reasons in customer-owned allow, observe, challenge, review, or block policies.
- **Agent identity and control:** apply separate trust policies to supported signed agents and unknown automation when the module is enabled.
- **Investigation and operations:** review device records, trends, policy outcomes, audit history, alerts, and eligible exports in Backoffice.
- **Integrations:** consume browser events, scoped backend reads, SDKs, event delivery, exports, and eligible read-only MCP access.

See the [Customer Capability Reference](https://noxtica.com/docs/features/) for every public family, where it appears, what it produces, and what must be enabled.

### Platform Components

| Component               | Customer purpose                                                                              | Availability boundary                                                                            |
| ----------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **Browser collector**   | Collect and submit an eligible assessment; return browser events and cache state              | Requires an activated domain and Site Key; optional signal families have separate policy gates   |
| **Collector service**   | Score submissions and expose supported verification and lookup APIs                           | Endpoints, quotas, and modules vary by tenant and contract                                       |
| **Backoffice**          | Configure domains and eligible modules; review analytics, records, actions, access, and usage | Pages and actions are filtered by operator role, tenant scope, and entitlement                   |
| **Server API and SDKs** | Read results and make decisions from trusted backend code                                     | Requires a secret key with the necessary scope; never place server credentials in the browser    |
| **Integration outputs** | Deliver eligible events through webhooks, sinks, exports, or read-only MCP                    | Requires destination/token configuration and any applicable module, role, and data-policy review |

## Quick Start

### 1. Get Your Site Key

Request access through [Contact](https://noxtica.com/contact/). After your account is provisioned, sign in to [Backoffice](https://backoffice.noxtica.com), add the exact production or staging origin under **Domains**, and copy its Site Key. Keep environments separate; a Site Key is public but origin-bound.

### 2. Add the Collector

Copy your domain's snippet from **Backoffice → Integrations & API → Script & Consent**, then follow the [install walkthrough](https://noxtica.com/docs/browser-runtime/#install-core-on-every-page-extensions-after-consent). It is the single source for the core and extensions scripts, stable or pinned tags, the replay recorder head, CSP, consent modes, protected actions, and the check that it works.

### 3. Receive Risk Scores

Listen for the documented result event after successful collection or a cache hit:

```javascript
document.addEventListener('noxtica:collected', (event) => {
	const { fingerprintId, score, risk_level, confidence, flags, fromCache } = event.detail;

	// Send the device handle to your backend with the customer action.
	// Treat score, confidence, and flags as policy inputs—not an identity verdict.
});
```

Do not put a secret Server API key in this handler. Use the browser result to shape reversible experience choices or send its device handle to your backend for a trusted lookup.

### 4. Server-side Lookups (Optional)

Create a Server API key in **Backoffice → API Config**, select the narrowest required scope, save the secret when shown, and call the supported endpoint from your backend:

```bash
curl -H "Authorization: Bearer sk_prod_your_api_key" \
  "https://collect.noxtica.com/v1/device/DEVICE_ID"
```

Handle `401`, `403`, `404`, and `429` explicitly. A missing or expired device should follow your `unknown` path rather than being treated as safe or malicious. See [Backend Integration](https://noxtica.com/docs/backend-integration/) for response fields, caching, and error handling.

## Guides

### Integrate

- **[Getting Started](https://noxtica.com/docs/getting-started/):** account prerequisites, the evaluation path, and application responsibilities.
- **[Install & Browser Runtime](https://noxtica.com/docs/browser-runtime/):** the single install guide: core and extensions scripts, stable or pinned tags, replay recorder head, CSP, consent modes, protected actions, single-page apps, storage disclosure, and the check that it works.
- **[Backend Integration](https://noxtica.com/docs/backend-integration/):** scoped server keys, trusted lookups, errors, rate limits, and backend decision patterns.

### Decide and investigate

- **[Detection Signals](https://noxtica.com/docs/detection-signals/):** what each evidence layer contributes and how missing evidence affects confidence.
- **[Threat Categories](https://noxtica.com/docs/threat-categories/):** public reason families, appropriate uses, and common false-positive boundaries.
- **[Why Calibration, Not Verdicts](https://noxtica.com/docs/why-calibration/):** map risk and confidence to route-specific policy.
- **[Use Cases](https://noxtica.com/docs/use-cases/):** reference patterns for marketplaces, financial services, identity-sensitive flows, and agent governance.

### Operate and govern

- **[Customer Capability Reference](https://noxtica.com/docs/features/):** the complete customer-facing capability directory with surfaces, outputs, eligibility, and limits.
- **[Impact by Audience](https://noxtica.com/docs/impact-audiences/):** responsibilities and outcomes for security teams, platforms, end users, and agent owners.
- **[Platform Overview](https://noxtica.com/docs/platform-overview/):** the reference version of the home-page sections, from customer value and the platform tour to capability families, principles, replay context, AI guardrails, and next steps.
- **[Pricing Reference](https://noxtica.com/docs/pricing/):** the explanatory text behind the pricing page — billing disclosures, comparison dimensions, add-ons, KYC and metered-module notes, estimator definitions, and commercial FAQ.
- **[Engineering Principles](https://noxtica.com/docs/principles/):** the operational review checks behind defensible decisions.
- **[Concepts & Glossary](https://noxtica.com/docs/concepts/):** shared terms for device intelligence, agent controls, browser security, MCP, and the assistant.

<!-- docs-map:start -->
## Browse by section

Every customer-facing feature has one task-oriented page with the same layout: what it is, prerequisites, steps, how to verify, troubleshooting and related pages. The Server APIs section is the generated API reference.

### Server APIs

- [Server API reference](https://noxtica.com/docs/api/): authentication, errors, rate limits, webhooks, the MCP server and the generated endpoint reference.

### Browser SDK

- **[Install & Browser Runtime](https://noxtica.com/docs/browser-runtime/):** The one install guide for the Noxtica collector: core and extensions scripts, stable or pinned tags, recorder head, CSP, consent, protected actions, and checks.
- **[Script attributes and client options](https://noxtica.com/docs/sdk/script-attributes/):** Every data-* attribute on the Noxtica script tag and every createClient or init option, with accepted values, defaults and effect.
- **[Client API, events and the command queue](https://noxtica.com/docs/sdk/client-api/):** The page globals, the methods of window.noxticaClient, every noxtica:* event, the window.noxtica command queue and the checkOnce result, as the loader implements them.
- **[Consent modes, GPC and Google Consent Mode](https://noxtica.com/docs/sdk/consent/):** Set a consent mode per domain, declare it on the tag, connect your banner to the four categories, handle GPC and DNT, bridge Google Consent Mode v2 and test it.
- **[Protected actions: client trigger and server check](https://noxtica.com/docs/sdk/protected-actions/):** Declare protected actions per domain, trigger the minimal check from a form or code, carry the request id to your backend and redeem it with the verify call.
- **[Single-page apps, frameworks and tag managers](https://noxtica.com/docs/sdk/single-page-apps/):** Load the Noxtica collector once in a single-page app, handle route changes and framework forms, and install it through a tag manager or a CMS theme.
- **[Content Security Policy, hosts and first-party relay](https://noxtica.com/docs/sdk/csp-and-relay/):** Allow the collector and ingest hosts in your Content Security Policy, know what degrades without WebAssembly, and serve the collector from your own subdomain.
- **[Browser SDK troubleshooting](https://noxtica.com/docs/sdk/troubleshooting/):** Match a browser collector symptom to its cause and fix: token errors, consent gating, extension load reasons, CSP, duplicate tags and browser limits.
- **[SDK family and availability: browser, server and mobile](https://noxtica.com/docs/sdk/family/):** What the browser script, the typed browser wrapper, the server and mobile SDKs, Postman and OpenAPI are for, their source versions and how to get access.
- **[SDK Changelog](https://noxtica.com/docs/changelog/):** Release notes for the Noxtica browser collector SDK: what changed in each version, who is affected, what to do, and which @noxtica/sdk version pairs with which collector release.

### Identity verification

- **[Identity verification integration](https://noxtica.com/docs/identity-verification-integration/):** Create a hosted identity verification session from your server, send the customer to the link, and read the outcome by status read or signed event.
- **[Self-hosted identity verification (direct API)](https://noxtica.com/docs/identity-verification-self-hosted/):** Call the identity verification API directly from your server: mint a nonce, run a verification, read the result, and learn what the direct route does and does not cover today.
- **[Invitations and hosted verification settings](https://noxtica.com/docs/identity-verification-invitations/):** Set up the hosted verification page in Backoffice, record the legal basis, send a customer a one-time verification link without code, and read the result.
- **[Identity verification events and webhooks](https://noxtica.com/docs/identity-verification-webhooks/):** Register a signed HTTPS endpoint in Backoffice, verify every delivery, and handle each identity verification event: when it fires, its fields, retries and duplicates.
- **[Noxtica Verification ID (NVID)](https://noxtica.com/docs/identity-verification-id/):** Read a Noxtica Verification ID from the session status or an event, understand its statuses and validity, share the public status link, and revoke or resend it in Backoffice.
- **[Business and merchant verification (KYB and KYM)](https://noxtica.com/docs/identity-verification-business/):** Create hosted business (KYB) and merchant (KYM) onboarding sessions, follow them in Backoffice and receive notify-only events. Availability depends on your organisation.
- **[Verification data: storage, access and deletion](https://noxtica.com/docs/identity-verification-data/):** What happens to identity, business and merchant verification details and evidence over time, who can see them, and how a tenant administrator deletes them.
- **[Identity verification FAQ and troubleshooting](https://noxtica.com/docs/identity-verification-faq/):** Short answers to the questions integrators ask about hosted identity verification: statuses, review, links, keys, events, the Verification ID and data, plus a five-step triage.
- **[Identity verification operations in Backoffice](https://noxtica.com/docs/identity-verification-operations/):** Work the Backoffice KYC pages day to day: read cases, decide the review queue, follow processes, manage policies, screening, recovery, delegations, evidence access and device trust.
- **[KYC Hosted Sessions](https://noxtica.com/docs/kyc-hosted-sessions/):** How long a hosted KYC verification link stays open, and what your backend sees once it expires.

### Observability: RUM, replay, APM and SEO

- **[Observability overview: RUM, replay, APM and ingest](https://noxtica.com/docs/observability/overview/):** Map each browser observability tool to what it measures, the Backoffice page that shows it, what you install, and the consent and legal-basis gates it needs.
- **[Real user monitoring and Web Vitals](https://noxtica.com/docs/observability/rum/):** Turn on real user monitoring for a domain, record its consent and Do Not Track decision, and read Web Vitals, errors and SDK health in Backoffice.
- **[Browser errors, console logs and source maps](https://noxtica.com/docs/observability/errors-and-source-maps/):** Capture redacted JavaScript errors and masked console logs, upload source maps from your build, and read grouped errors on the Issues page.
- **[Session replay: setup, masking and playback](https://noxtica.com/docs/observability/session-replay/):** Arm session replay for a domain, choose what is masked, set sampling and limits, then find and play back recorded sessions in Backoffice.
- **[Custom events, session tags and request tracing](https://noxtica.com/docs/observability/events-and-tracing/):** Send custom events, tag and identify sessions without sending raw ids, and join a browser request to your backend with W3C trace headers.
- **[Behavior analytics: heatmaps, journeys and funnels](https://noxtica.com/docs/observability/behavior-analytics/):** Switch on the tracker for a domain, then read click and scroll heatmaps, page-to-page journeys and app-event funnels in Backoffice.
- **[APM and the ingestion service (OTLP)](https://noxtica.com/docs/observability/apm-and-ingest/):** Mint an Ingestion API key in Backoffice, point an OpenTelemetry exporter at the ingestion service, send a test trace and a release marker, and find them in the APM explorers.
- **[SEO tools: page checks, site crawls and search score](https://noxtica.com/docs/observability/seo-tools/):** Prove you own a hostname, run a single-page SEO check or a bounded site crawl in Backoffice, read the issues and the search score, and see Core Web Vitals history.
- **[Connect Google Search Console for a domain](https://noxtica.com/docs/observability/search-console/):** Connect a domain to its own Google Search Console property with a service account key or your own OAuth client, test the connection, and use it as ownership proof for SEO tools.
- **[Uptime checks, alerts, status reports and the status page](https://noxtica.com/docs/observability/uptime-alerts-status/):** Add verified uptime checks, route alerts to Slack, Teams, Telegram, e-mail or a signed webhook, turn periodic status reports on or off, and follow the public status page and its Atom feed.

### Hunter, Spot and Pulse

- **[Hunter browser extension](https://noxtica.com/docs/hunter/extension/):** Run a local audit of which scripts on one page probe browser fingerprinting APIs, read and export the report, and optionally send one previewed report to your Noxtica workspace.
- **[Hunter reports in Backoffice](https://noxtica.com/docs/hunter/reports/):** Create a short-lived upload token, review Hunter page-audit reports your team sent to the workspace, download the stored JSON, and delete one report or every report from one reporter.
- **[Spot captures](https://noxtica.com/docs/hunter/spot/):** Connect the Spot extension with a short-lived token, record one tab or desktop capture with bounded developer context, then review, share and delete captures in Backoffice.
- **[Noxtica Pulse: endpoint telemetry overview](https://noxtica.com/docs/pulse/overview/):** Understand what Noxtica Pulse is, who sees what, how Backoffice configures it, what the desktop client and the player site do, and where the privacy controls and server API are.
- **[Pulse in Backoffice: applications, profiles, bundles and rollouts](https://noxtica.com/docs/pulse/backoffice/):** Register a Pulse application, author and validate a profile, publish it as a signed bundle, follow the staged rollout, and halt, resume or roll back from Backoffice.
- **[Pulse detections, response, devices and privacy](https://noxtica.com/docs/pulse/detections-and-privacy/):** Review Pulse detections with a person in the loop, answer appeals, set the response ladder, manage devices and attestation, read the privacy page, and use the tenant API and webhooks.

### Security administration and attestation

- **[Device and app attestation](https://noxtica.com/docs/security/attestation/):** Register Android and iOS apps for Play Integrity and App Attest, call the two mobile attestation routes from your backend, and read the results in Backoffice.
- **[Sign-in, SSO, SCIM, MFA and IP allowlist](https://noxtica.com/docs/security/sign-in-and-access/):** Set up how your team signs in to Backoffice: passwords, authenticator apps, security keys, SSO, SCIM, a tenant-wide MFA rule, IP allowlists, sessions and invitations.
- **[Roles and permissions](https://noxtica.com/docs/security/roles-and-permissions/):** See what the viewer, analyst, admin and billing roles can do in Backoffice, which actions need a step-up MFA check, and how admins manage users, disabling and MFA resets.
- **[Audit log and data export](https://noxtica.com/docs/security/audit-log-and-exports/):** Read who changed what in your Backoffice workspace, filter and export the audit log, run a data export, and review export history. Includes limits and the API export route.

### Backoffice guide

- **[Backoffice guide: navigation, roles and shortcuts](https://noxtica.com/docs/backoffice/overview/):** Find any Backoffice page, see which role can open it, and move faster with the command palette, G shortcuts, the workspace switcher and page help.
- **[Domains, site keys and the install card](https://noxtica.com/docs/backoffice/domains/):** Register a domain, copy its public site key, open the install card, and manage the per-domain settings, key rotation and deletion in Backoffice.
- **[Fingerprints, analytics and live monitoring](https://noxtica.com/docs/backoffice/fingerprints-and-analytics/):** Search device fingerprints, read a device record, watch live traffic, compare devices and use the analytics, geo-risk and hardware attestation views in Backoffice.
- **[Risk actions, investigations and entity lookup](https://noxtica.com/docs/backoffice/risk-actions-and-investigations/):** Use Risk Actions, Agentic Security, Bot Intelligence, Behavioral Corroboration, Investigations, Entity Lookup and Quality & Calibration to validate policy before you enforce it.
- **[Detection and collection settings](https://noxtica.com/docs/backoffice/detection-settings/):** Tune rules, risk scoring, client cost levels, verdict bands, honeypots, the collector refresh interval, probes and behavioral signals, and roll changes out in a safe order.
- **[Integrations and API pages](https://noxtica.com/docs/backoffice/integrations/):** A map of the Integrations & API sidebar group: what each page does, who can open it, which credentials it mints, and which documentation page covers it.
- **[Event sinks (SIEM export)](https://noxtica.com/docs/backoffice/event-sinks/):** Create an event sink that pushes signed verdict and audit events to your SIEM, arm it, send a test request, inspect deliveries and rotate its signing secret.
- **[AI assistant, MCP tokens and coding-agent keys](https://noxtica.com/docs/backoffice/ai-assistant-and-mcp/):** Open the Backoffice assistant, set model routing and provider keys, mint MCP tokens with read scopes, and create coding-agent keys, with the limits Backoffice shows.
- **[Workspace gates, feature flags, data operations and mobile operations](https://noxtica.com/docs/backoffice/workspace-settings/):** Use Workspace Gates, visitor Feature Flags, Data Operations, Mobile Operations and your personal Settings and Notifications in Backoffice, with the roles and MFA checks each needs.

### Billing and usage

- **[Plans, packages and add-ons](https://noxtica.com/docs/billing/plans-and-packages/):** Request a plan change or extra capacity, compare and subscribe to packages, turn module add-ons on, and read why an item is unavailable before you click it.
- **[Usage, quotas and metering](https://noxtica.com/docs/billing/usage-and-quotas/):** Read your usage against plan quotas in Backoffice: the Usage & Quotas tabs, the meters, how each quota counts, what happens at the limit, KYC usage, and how to set a quota alert.
- **[Wallet, invoices and reports](https://noxtica.com/docs/billing/wallet-invoices-reports/):** Add funds to your wallet, set a low-balance warning, read the ledger and AI credits, open invoices, review sent reports, and control status-report e-mails in Backoffice.
- **[Billing status, grace period and reminders](https://noxtica.com/docs/billing/status-grace-reminders/):** Understand the Backoffice billing banners, the package grace window and what pauses when it ends, and the schedule of billing reminder e-mails, so you can act before service pages pause.

### Compliance and legal

- **[Privacy and compliance controls in Backoffice](https://noxtica.com/docs/compliance/overview/):** Find every Privacy & Legal and Web Analytics & Privacy page in Backoffice, who can use it, what it records and which docs page explains it.
- **[Legal basis register and receipts](https://noxtica.com/docs/compliance/legal-basis/):** Record, change and withdraw the legal basis your organisation asserts for gated features, and learn which features refuse to start without a receipt.
- **[Data retention, raw IP storage and data locations](https://noxtica.com/docs/compliance/retention-and-locations/):** Set how long browser intelligence data is kept, decide whether full IP addresses are stored, and read where each kind of your data is stored.
- **[Data subject scope, erasure requests and account deletion](https://noxtica.com/docs/compliance/requests-and-deletion/):** Learn which deletion routes exist in Backoffice, how an administrator removes end-user data, and how identity verification data and accounts are deleted.
- **[Cookies, storage and consent categories for your site](https://noxtica.com/docs/compliance/cookies-and-storage/):** List the cookies and browser storage the Noxtica SDK writes, map each to a consent category, disclose them in your cookie policy and set DNT and GPC behaviour.
- **[DPA, sub-processors, DPIA pointers and assurance](https://noxtica.com/docs/compliance/assurance-and-subprocessors/):** Find the public DPA and sub-processor pages, accept the AI assistant as a sub-processor in Backoffice, and know where to ask for DPIA and assurance material.

<!-- docs-map:end -->

## Risk Levels

Every assessment can include a numeric score and one of five plain-language levels. The fixed ranges below describe the current public response contract; they are not universal action thresholds.

| Score  | Level      | Interpret as                                     | Common starting action                                 |
| ------ | ---------- | ------------------------------------------------ | ------------------------------------------------------ |
| 0–19   | `minimal`  | Little risk evidence in the available assessment | Allow; retain normal controls                          |
| 20–39  | `low`      | Minor or explainable anomalies                   | Allow and observe                                      |
| 40–59  | `medium`   | Mixed or incomplete suspicious evidence          | Observe or use a low-friction step-up                  |
| 60–79  | `high`     | Strong suspicious evidence                       | Challenge, hold, or review                             |
| 80–100 | `critical` | Multiple or strong reason families agree         | Strong challenge or block only under a reviewed policy |

Confidence answers a separate question: how much usable evidence supported the assessment. Low confidence should normally move a decision toward defer, collect more evidence, or a reversible challenge—not toward an irreversible block.

## Dashboard

Manage your activated account in **[Backoffice](https://backoffice.noxtica.com)**. Start with the selected tenant and domain, then use **Analytics** for population behavior, **Fingerprints** for individual records, **Risk Actions** for policy outcomes, and **Usage** for current limits. The pages you see depend on your role and enabled modules.

## At a Glance

- **Integration model:** domain-bound browser Site Key plus optional scoped server credentials.
- **Primary output:** score, five-level risk tier, confidence, named flags/reasons, and a tenant-scoped device handle.
- **Collection cadence:** cached and configurable; `checkOnce()` respects the applicable interval.
- **Decision owner:** your route-specific policy; Noxtica supplies evidence and eligible enforcement surfaces.
- **Availability:** plan, contract, role, tenant/domain configuration, client support, quota, and legal-basis gates can apply.
- **Performance:** measure your selected client, configuration, geography, network, and cache mix; this page makes no universal latency or availability commitment.

## Support

- **Access, provisioning, commercial eligibility, or technical support:** [Contact us](https://noxtica.com/contact/).
- **Before opening a ticket:** include the tenant and domain, timestamp, customer-visible symptom, relevant request or device handle, and whether the result was cached. Do not send Server API secrets or unnecessary personal data.
- **Capability question:** link the applicable [capability family](https://noxtica.com/docs/features/) and note whether its page or setting is visible in Backoffice.

---

Source: https://noxtica.com/docs/ai-agents/
Markdown: https://noxtica.com/docs/ai-agents/index.md
Last updated: 2026-10-28

# Integrate with an AI agent

Many Noxtica integrations are written with an AI coding agent or an AI assistant. This page shows how to give such an agent the documentation in a form it can read, the order of steps it follows, the rules it must keep, and prompts to start from. Everything the agent needs is published on these pages; it needs no private repository and no credential to read them.

Availability is account-specific, as everywhere in the documentation: the modules enabled for your organisation decide which steps apply to you.

## Give the agent the documentation

Every documentation page is published as clean Markdown, without navigation, search box, table of contents or footer text. Choose the surface that fits the agent's context window.

| Surface | URL | Use it when |
| --- | --- | --- |
| Index | [llms.txt](https://noxtica.com/llms.txt) | The agent should find the right page itself. Pages are grouped by task, in integration order, one line each. |
| Full text | [llms-full.txt](https://noxtica.com/llms-full.txt) | The agent can read the whole documentation in one go. The file is large: `llms.txt` states its size. It leaves out the generated API reference pages, which the OpenAPI files cover. |
| One page | `https://noxtica.com/docs/<path>/index.md`, for example [Getting Started](https://noxtica.com/docs/getting-started/index.md) | The task names a page. The body is the page text, with frontmatter (`title`, `description`, `canonical_url`, `last_updated`, `section`) and absolute links. |
| Content negotiation | The page URL with the request header `Accept: text/markdown` | The agent already has the page URL. The response is the same document as the `index.md` URL. |
| OpenAPI | [openapi.json](https://noxtica.com/docs/api/openapi.json) or [openapi.yaml](https://noxtica.com/docs/api/openapi.yaml) | The agent generates or checks client code. One document with every public operation, parameter and webhook of the published release. |
| One API | `https://noxtica.com/docs/api/openapi/<api>.json` or `.yaml`, with `<api>` one of `v1`, `kyc`, `pulse`, `mcp` | The task touches one API and a smaller file fits the context window. |
| API reference | [API reference](https://noxtica.com/docs/api/reference/) | A person or an agent needs the operations in prose and tables, one page per area. |

Every HTML documentation page also announces its Markdown twin with `<link rel="alternate" type="text/markdown">` in the head and a `Link` response header.

```bash
# The same page, two ways.
curl -s https://noxtica.com/docs/getting-started/index.md
curl -s -H 'Accept: text/markdown' https://noxtica.com/docs/getting-started/
```

## Follow the integration steps in this order

Each step names the page that holds it. An agent that skips ahead tends to guess; give it one step at a time and let it read the linked page first.

1. **Choose one protected moment.** Pick a signup, login, checkout or recovery step, and decide what happens when no fresh evidence is available. See [Getting Started](https://noxtica.com/docs/getting-started/) and [Integration Flow](https://noxtica.com/docs/integration-flow/).
2. **Register the domain and read its public Site Key.** A person does this in Backoffice. See [Domains, site keys and the install card](https://noxtica.com/docs/backoffice/domains/).
3. **Install the browser collector.** Load the core script on every page and the extensions after consent. See [Install & Browser Runtime](https://noxtica.com/docs/browser-runtime/) and [Script attributes and client options](https://noxtica.com/docs/sdk/script-attributes/).
4. **Set the consent mode and connect your banner.** See [Consent modes, GPC and Google Consent Mode](https://noxtica.com/docs/sdk/consent/) and [Cookies, storage and consent categories for your site](https://noxtica.com/docs/compliance/cookies-and-storage/).
5. **Declare protected actions and trigger the check.** The browser hands your backend a request id. See [Protected actions: client trigger and server check](https://noxtica.com/docs/sdk/protected-actions/).
6. **Create a server key and authenticate.** A person creates the key in Backoffice; the server keeps it in its secret store. See [API authentication](https://noxtica.com/docs/api/authentication/).
7. **Verify on your server.** Redeem the request id or read the device from the backend, and keep the result states separate. See [Backend Integration](https://noxtica.com/docs/backend-integration/).
8. **Add identity verification when it is enabled for you.** Create a hosted session from the server and read the outcome. See [Identity verification integration](https://noxtica.com/docs/identity-verification-integration/).
9. **Receive webhooks.** Verify the signature of every delivery before you act on it. See [API webhooks](https://noxtica.com/docs/api/webhooks/).
10. **Handle errors and limits.** See [API errors](https://noxtica.com/docs/api/errors/) and [API rate limits](https://noxtica.com/docs/api/rate-limits/).
11. **Compare before you enforce.** Run the policy in observation mode and compare proposed actions with outcomes before any block or challenge. See [Getting Started](https://noxtica.com/docs/getting-started/).
12. **Optional: connect an MCP client.** See [Connect an MCP client](https://noxtica.com/docs/api/mcp/).

## Rules an agent must keep

Give the agent these rules in its instructions, next to the task.

### Credentials

- Use placeholders in code, prompts and examples: `pk_prod_your_site_key_here` for the public Site Key and `sk_prod_your_api_key` for a server key. Read the real value from an environment variable such as `NOXTICA_SERVER_KEY` at run time.
- Never put a real server key (`sk_…`), MCP token (`mcp_…`), ingestion key, webhook signing secret or Backoffice credential into a prompt, a chat, an issue, a log or a commit. If one reached an agent anyway, revoke it in Backoffice and create a new one.
- Keep server credentials out of browser code, URLs, client logs and analytics. The browser holds the public Site Key only.
- Create keys, tokens and webhook endpoints in Backoffice. An agent does not create them, and the documentation does not ask it to.

### Consent and people

- Do not grant consent on behalf of a visitor. Call `setConsent` only with the visitor's own choice, and do not switch a domain to a consent mode that skips the decision just to get past a failing check. The consent mode is a decision for your privacy owner.
- Do not create an identity verification session for a person who did not ask for one. The legal basis is recorded by an authorised person in your organisation before a session can be created.
- Treat a device identifier as a lookup handoff, not as an identity credential.

### Results and traffic

- Do not turn a score into a "bot or human" verdict. Read the risk, the confidence and the reasons, and keep `missing`, `invalid`, rate-limited and unavailable results distinct from low risk.
- Call only the hosts and operations the documentation and the OpenAPI files name. An operation that is not in them is not part of the public API.
- On HTTP `429`, wait for the number of seconds in `Retry-After`. Do not hard-code a limit: limits depend on the operation and on your account.
- Read a session status before you act on an event, and verify the signature of every webhook delivery.
- A write-capable MCP token only plans a change. A person approves each plan in Backoffice; an agent never applies one.

## Start from a prompt

Copy a prompt, replace the text in angle brackets, and add the rules above. Each prompt names the pages the agent must read first.

### Plan the integration

```text
You are integrating Noxtica into <my application>. Read https://noxtica.com/llms.txt, then
https://noxtica.com/docs/ai-agents/index.md, https://noxtica.com/docs/getting-started/index.md
and https://noxtica.com/docs/integration-flow/index.md.
Propose a plan for one protected moment: <signup | login | checkout | recovery>. List each step in the
order of the documentation, name the page that holds it, say which step a person must do in Backoffice,
and say what the application does when Noxtica returns no fresh evidence.
Do not write code yet. Use the placeholders pk_prod_your_site_key_here and sk_prod_your_api_key.
```

### Install the browser collector with consent

```text
Read https://noxtica.com/docs/browser-runtime/index.md and https://noxtica.com/docs/sdk/consent/index.md.
Add the Noxtica core script to every page of <my front-end framework> and load the extensions only after the
visitor consents through <my consent banner>. Use the public Site Key placeholder pk_prod_your_site_key_here.
Show the Content Security Policy change from https://noxtica.com/docs/sdk/csp-and-relay/index.md.
Never call setConsent for a category the visitor has not chosen.
```

### Verify on the backend

```text
Read https://noxtica.com/docs/backend-integration/index.md, https://noxtica.com/docs/sdk/protected-actions/index.md
and https://noxtica.com/docs/api/authentication/index.md.
Write the server handler in <my language and framework> that receives the request id from the browser,
redeems it with the server key from the environment variable NOXTICA_SERVER_KEY, and returns one of these
states: received, missing, invalid, rate limited, unavailable. Treat every state except received as "no
fresh evidence", never as low risk. On 429 honour Retry-After. Do not log the key.
```

### Create an identity verification session

```text
Read https://noxtica.com/docs/identity-verification-integration/index.md and
https://noxtica.com/docs/api/webhooks/index.md. Use https://noxtica.com/docs/api/openapi/kyc.json for the
request and response shapes.
Write the server code that creates a hosted session with my own opaque customer reference, redirects the
customer to the returned link, and reads the session status. Verify the signature of every
kyc.session.completed delivery and read the status before acting on it. Use the placeholder
sk_prod_your_api_key and never print it.
```

### Review an integration against the documentation

```text
Read https://noxtica.com/llms-full.txt. Review the Noxtica integration in this repository against it.
Report, per file: a server key reachable from browser code, a consent category granted without a visitor
choice, a result state treated as low risk, a missing Retry-After handling, a webhook handled without
signature verification. Quote the documentation page for each finding and propose the smallest fix.
```

## Connect an agent through MCP

An MCP client can read your workspace data with a scoped token. The endpoint is one HTTPS URL that speaks JSON-RPC 2.0; the token is a static bearer token that a person creates in Backoffice under Integrations & API, so configure the client with a custom `Authorization` header. Start with a read token and call `tools/list` to see what it may use. See [Connect an MCP client](https://noxtica.com/docs/api/mcp/) and [MCP integration](https://noxtica.com/docs/concepts/mcp-integration/).

## Common questions

### Do I need a key to read the documentation?

No. Every documentation page, `llms.txt`, `llms-full.txt` and the OpenAPI files are public. A key is needed only when the integration you build calls a server API.

### Can the agent create keys or change settings for me?

No. A person creates keys, tokens, webhook endpoints and consent settings in Backoffice. An MCP token with write access can only plan a change, and a person approves it.

### Which is authoritative, the Markdown or the HTML page?

The HTML page at its canonical URL. The Markdown is generated from the same source text, and every Markdown document names its `canonical_url` and the `last_updated` date.

### Where do I find the exact request and response shapes?

In the OpenAPI files and the [API reference](https://noxtica.com/docs/api/reference/). Each reference page names the OpenAPI release it comes from.

---

Source: https://noxtica.com/docs/getting-started/
Markdown: https://noxtica.com/docs/getting-started/index.md
Last updated: 2026-10-27

# Getting Started

This guide is the starting point for a Noxtica technical evaluation. The [developer overview](https://noxtica.com/developers/) links each step to the page that holds it.

## Before you integrate

Request a technical evaluation so the team can provision the exact browser origin, public Site Key, and server access needed for the evaluated path. Do not copy credentials or package names from private repositories, old examples, or another environment.

The current publicly verified browser release is the loader served from the Noxtica collector origin. No public npm package, framework wrapper, native SDK, server SDK, or Postman collection passed the 2026-09-20 release check, so this guide does not provide installation commands for them. They exist as private deliveries that your account team arranges: see [SDK family and availability](https://noxtica.com/docs/sdk/family/). The public API operations are published as an OpenAPI description at [openapi.json](https://noxtica.com/docs/api/openapi.json), and [Integrate with an AI agent](https://noxtica.com/docs/ai-agents/) shows how to hand these docs to an AI coding agent.

## Automatic collection (recommended)

Copy your domain's snippet from **Backoffice → Integrations & API → Script & Consent** and follow the [install walkthrough](https://noxtica.com/docs/browser-runtime/#install-core-on-every-page-extensions-after-consent), the single source for the scripts, CSP, consent modes, and checks.

## Shortest maintained path

1. Use the [browser sample](https://noxtica.com/docs/browser-runtime/#browser-handoff-sample) from the checked fixture.
2. Observe both the collection-complete and collection-error paths.
3. Send only the returned device identifier to your own backend.
4. Use the [server sample](https://noxtica.com/docs/backend-integration/#read-the-device-on-your-server) for the authenticated device lookup.
5. Exercise received, missing, invalid, rate-limited, and unavailable states with the [result-state sample](https://noxtica.com/docs/backend-integration/#keep-result-states-separate).
6. Compare proposed policy actions with outcomes in observation mode before enforcement.

## Application responsibility

The browser collector does not make your final signup, login, checkout, recovery, or access decision. Browser capability, tenant policy, privacy signals, and consent state can reduce or prevent collection. Your application must remain usable and apply its chosen fallback when no fresh evidence is available.

Keep server credentials out of browser code, URLs, client logs, and analytics. A device identifier is a lookup handoff, not an identity credential.

## Verify the evaluation

Confirm the exact origin is provisioned, collection can complete, the unavailable path remains usable, the backend can perform an authenticated read, and every non-success state stays distinct from low risk. Successful installation alone does not establish a production-ready policy.

Continue with [Install & Browser Runtime](https://noxtica.com/docs/browser-runtime/), [Backend Integration](https://noxtica.com/docs/backend-integration/), and [Integration Flow](https://noxtica.com/docs/integration-flow/).

---

Source: https://noxtica.com/docs/integration-flow/
Markdown: https://noxtica.com/docs/integration-flow/index.md
Last updated: 2026-10-24

# Integration Flow

The [developer overview](https://noxtica.com/developers/) is the short evaluator path and current support matrix. This guide expands the ownership checkpoints without creating a second set of snippets.

## 1. Customer client

Load the verified public browser collector for the provisioned origin, using the snippet from **Backoffice → Integrations & API → Script & Consent** and the [install walkthrough](https://noxtica.com/docs/browser-runtime/#install-core-on-every-page-extensions-after-consent). The client reports either a collection result or an unavailable state. When a result contains a device identifier, pass only that identifier to your backend with the customer action it will inform.

JavaScript disabled, blocked collection, reduced capability, tenant policy, and consent state can change what evidence is available. The customer journey must remain usable.

## 2. Noxtica processing

Noxtica processes evidence admitted by the evaluated browser and tenant configuration. A completed browser result can expose less than the authenticated server record. Do not infer low risk from an absent browser score.

## 3. Customer server

Keep the credential secret and perform the authenticated v1 device lookup. Preserve received, missing, invalid, rate-limited, and unavailable states. Apply a deadline rather than waiting indefinitely on a customer-facing operation.

## 4. Customer policy

Your application combines the lookup with context it already owns. It chooses whether to continue, observe, request additional verification, review, or deny. Noxtica does not autonomously make that final customer decision.

## 5. Investigation and measurement

Confirm collection and lookup behavior, calculate proposed actions in observation mode, label outcomes from your own systems, review false-positive cost, and only then promote a bounded policy. Keep an owner and rollback path.

## Evaluation checkpoints

1. Provision the exact origin and public Site Key.
2. Observe collection and unavailable behavior.
3. Pass the returned identifier to the customer backend.
4. Perform an authenticated read with a server-held credential.
5. Exercise every result state in the maintained fixture.
6. Evaluate policy in observation mode before enforcement.

Continue with [Install & Browser Runtime](https://noxtica.com/docs/browser-runtime/) or [Backend Integration](https://noxtica.com/docs/backend-integration/).

---

Source: https://noxtica.com/docs/browser-runtime/
Markdown: https://noxtica.com/docs/browser-runtime/index.md
Last updated: 2026-10-27

# Install & Browser Runtime

**Find your snippet in the Backoffice → Integrations & API → Script & Consent** ([`/integrations/script-consent`](https://backoffice.noxtica.com/integrations/script-consent)). Pick the domain and the page generates the tags with that domain's Site Key and the current collector build, plus the consent mode, protected actions, and a verification checklist. This page is the public walkthrough of the same content: what to install, in which order, and how to check that it works. Every Site Key on this page is a placeholder (`pk_prod_your_site_key_here`); never copy a key, hash, or build name from a document.

The [developer overview](https://noxtica.com/developers/) links the integration guides in order. Other docs pages link here instead of repeating install steps.

## Current public surface

The public collector loader is served from the Noxtica collector origin, `https://collect.noxtica.com` unless your account has a provisioned collector host. This page calls that origin "your collector host". No public npm package, framework wrapper, native SDK, or cross-platform wrapper passed the 2026-09-20 release check described in [Getting started](https://noxtica.com/docs/getting-started/#before-you-integrate), so those surfaces are omitted rather than inferred from private inventory.

## Install: core on every page, extensions after consent

The collector is two scripts. Load the core on every page; load the extensions only when your consent mode allows it.

- The **core** (`noxtica-collector-core.js`) needs no consent. It obtains the session token, submits the minimal security check, answers server-requested challenges, offers the consent API and the extensions loader, and runs [protected actions](https://noxtica.com/docs/browser-runtime/#protected-actions). In a consent-gated mode it stores nothing on the visitor's device.
- The **extensions** (`noxtica-collector-extensions.js`) need consent. They carry persistent device recognition, the full device fingerprint, analytics, real-user monitoring and console logs, session replay, and behavioral signals. Each module still runs only when its category is granted.

```html
<script
	src="https://collect.noxtica.com/collector/noxtica-collector-core.js"
	data-site-key="pk_prod_your_site_key_here"
	data-auto-init
	data-auto-check-once
	async
></script>
```

| Attribute              | Purpose                                                                                                      |
| ---------------------- | ------------------------------------------------------------------------------------------------------------ |
| `data-site-key`        | The public Site Key of the exact origin. Keys are origin-bound: a token request from another origin is refused with `403` and `{"error":"Origin mismatch"}`. |
| `data-auto-init`       | Creates the client and assigns `window.noxticaClient`.                                                       |
| `data-auto-check-once` | Runs the cache-aware check (`checkOnce()`) once per page.                                                    |
| `data-extensions`      | Optional. `"auto"` makes the core load the extensions itself; any other value keeps that off.                |
| `async`                | The core never needs to block rendering.                                                                     |

Load the extensions in one of three ways:

- add `data-extensions="auto"` to the core tag: the core loads them immediately in `not_required` mode and on the first granted category in the `api` and cookie modes;
- call `await window.noxticaClient.loadExtensions()` after your page grants consent (see [Loading extensions](https://noxtica.com/docs/browser-runtime/#loading-extensions-and-its-result));
- inject `<script src="https://collect.noxtica.com/collector/noxtica-collector-extensions.js" async></script>` yourself after consent. It carries no Site Key and attaches to the core already on the page.

Loading the extensions never grants consent by itself. You can also switch **Auto-load extensions** on per domain in Script & Consent. In `not_required` mode that loads the extensions for every visitor, including those who declined your own banner, so treat it as a decision about your banner, not a convenience.

**Existing installs.** The legacy URLs `https://collect.noxtica.com/collector/noxtica-collector.js` and `/collector/noxtica.js` now serve the core and load the extensions automatically: immediately in `not_required` mode, after the first grant in the gated modes. Set `data-extensions` to any other value to opt out. The original combined bundle is deprecated and no longer offered; new installs use the core tag above.

**Device-analysis engines.** The KHAN and Obsidian engines are split the same way (`khan-core` and `obsidian-core`, then the matching extensions) and load automatically with the core and the extensions. You never add their tags.

## Stable or pinned snippets

Script & Consent generates two variants of each tag from the collector's live manifest, `https://collect.noxtica.com/collector/asset-manifest.json`.

- **Stable (default).** The unhashed URL always serves the current build and carries no `integrity` attribute, so the tag never needs updating.
- **Pinned with Subresource Integrity.** Use it only if your security policy requires an `integrity` attribute. A pinned tag references one exact content-hashed build:

```html
<script
	src="https://collect.noxtica.com/collector/noxtica-collector-core.<hash>.js"
	integrity="sha384-<from the manifest>"
	crossorigin="anonymous"
	data-site-key="pk_prod_your_site_key_here"
	data-auto-init
	data-auto-check-once
	async
></script>
```

Build it from the manifest: `assets["noxtica-collector-core.js"]` is the file name under `/collector/` and `integrity["noxtica-collector-core.js"]` is the `integrity` value. The extensions use the keys `noxtica-collector-extensions.js`. A pinned core loads the extensions with their own integrity hash, so you do not pin the extensions separately.

**How long a pin lasts.** The hashed core and extensions bundles of the last three previous releases keep resolving, byte-identical and immutable, and are listed in `previous[]` of the manifest. Copy the pinned tag again within three releases; after that the pinned file stops being served and the browser blocks it. Hashed files are never a substitute for the manifest: do not copy a hash from a document, including this one.

**The recorder head is the exception.** The early replay loader (`noxtica-recorder-head.js`) is not retained: its hashed URL stops resolving on the next recorder build, so the stable tag in the next section is the default.

## Replay recorder head

Session replay can start before the page paints. The recorder head is a small synchronous preloader that buffers a bounded early window in memory and has no transport. The asynchronous core drains it only after the configured replay admission checks allow capture; otherwise the queue is discarded. Sites that do not use replay may omit it.

```html
<script src="https://collect.noxtica.com/collector/noxtica-recorder-head.js" crossorigin="anonymous" data-cfasync="false"></script>
```

- It must be the **first executable script** in `<head>`, before anything else that runs.
- Load it **synchronously**: never `async`, `defer`, or `type="module"`.
- `data-cfasync="false"` stops Cloudflare Rocket Loader from deferring it.
- It needs an **armed replay policy** for the domain (Backoffice → Session Replay) and a consent flow that calls `setConsent` with the `replay` category.
- A pinned variant comes only from the live manifest key `noxtica-recorder-head.js`; keep `crossorigin="anonymous"` and `data-cfasync="false"`.

## Content Security Policy

If your site sends a Content Security Policy, add only what the collector needs, and merge the sources into your own lists; do not paste a vendor policy over yours. Hosts below are your collector host (`collect.noxtica.com` by default) and the ingest host (`ingest.noxtica.com`, derived automatically from the default collector host).

| Directive     | Allow                                                    | Why                                                                                                                                                    |
| ------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `script-src`  | your collector host and `'wasm-unsafe-eval'`             | Loads the core, extensions, and engine loaders. `'wasm-unsafe-eval'` lets the KHAN and Obsidian engines compile WebAssembly; it does not allow `eval()`. |
| `worker-src`  | `blob:` (keep your own entries, such as `'self'`)        | The engines start workers from `blob:` URLs. A worker script must be same-origin, so it cannot be served from the collector host.                       |
| `connect-src` | your collector host **and** the ingest host (only if your page declares one) | Token and submit calls go to the collector host. Analytics, RUM, console logs, and replay use the ingest host and fail over to the collector once, then stay there; a policy with only one of the two breaks half the traffic. |

If your domain uses server-requested challenges, also allow Cloudflare Turnstile as its documentation describes (`https://challenges.cloudflare.com`). The Script & Consent **CSP & storage** tab prints the same lines with your own hosts filled in.

```http
Content-Security-Policy:
  script-src 'self' https://collect.noxtica.com 'wasm-unsafe-eval';
  worker-src 'self' blob:;
  connect-src 'self' https://collect.noxtica.com https://ingest.noxtica.com;
```

- **`'wasm-unsafe-eval'` is needed.** Without it the engines cannot start; the SDK fails open, collection continues with reduced evidence, and a structured error is reported.
- **`'unsafe-eval'` is not needed.** Noxtica does not need `'unsafe-eval'`, and a policy without it produces no `eval` violation from Noxtica. The only Noxtica code that ever called `new Function(...)` was an optional KHAN diagnostic lane in the extensions runtime: a one-line capability probe, `new Function('return 0')`, and nine diagnostic programs. No score, verdict, or device identifier depends on it. The lane runs only while the signed token arms it, and from release r32 (2026-10-24) it is disarmed for every domain, so the runtime no longer evaluates dynamic code. If a site still sees `eval` reports, it is on an older token or a cached copy: an enforcing `script-src` reports one violation (blocked URI `eval`, source `…/collector/noxtica/noxtica-khan.js`) and a report-only policy about ten per consented visit. Reload with a fresh page load to get a current token; no policy change is needed. Do not add `'unsafe-eval'` for Noxtica.
- **`chrome-extension:` reports are probe noise.** On Chromium, with the `behavioral` category granted, the extension probe requests a few `chrome-extension://…` resources through script tags. An enforcing `script-src` can report them. The probe reads a blocked or missing resource as "not installed", so do not allow `chrome-extension:` for Noxtica.
- **Hash or nonce next to `'unsafe-inline'`.** Browsers that see a hash or nonce ignore `'unsafe-inline'`, which breaks every other inline script. If your policy relies on `'unsafe-inline'`, do not add a hash or nonce for the inline listener without a full nonce migration; if you already use nonces, give the inline listener its nonce.
- **Probe periodically.** A permissive policy hides what it allows: with `'unsafe-inline'` and `'unsafe-eval'` listed, report-only telemetry sees no inline or eval use. Send a stricter policy as a second, report-only header for a day before you tighten the enforcing one, and read the reports. It changes nothing on the page:

```http
Content-Security-Policy-Report-Only: script-src 'self' https://collect.noxtica.com; worker-src 'self'; connect-src 'self' https://collect.noxtica.com https://ingest.noxtica.com; report-uri /csp-report
```

## Consent modes (tenant integration guide)

Consent modes let a domain split the collector into a consent-free core and consent-gated categories. New domains start in `api` mode: the page check is skipped (`noxtica:collected` carries `skipped: 'consent_required'`) and nothing persistent is written until your page calls `setConsent`. Domains that already existed keep the mode they have, so an existing install changes nothing. `not_required` remains an explicit choice that keeps the behavior from before consent modes existed.

### Choosing a mode

Set the mode per domain in **Backoffice → Integrations & API → Script & Consent** (the Consent & extensions tab), stored as the domain's `client_consent_mode`. The collector reads it when it issues the browser token.

| Mode                    | Behavior                                                                                                                                                                                                                       |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `not_required`          | Not a consent gate. Domains created before the `api` default and never changed keep this mode, and you can choose it explicitly. Collection runs as configured today. An explicit `denied` from your page is still honored for that category. |
| `api`                   | The default for new domains. Every category starts denied. Your page grants or denies categories with `client.setConsent(...)`, usually from your consent management platform (CMP).                                                          |
| `cookie:<name>`         | The collector reads the first-party cookie `<name>`. Present and non-empty means every category is granted; absent or empty means every category is denied.                                                                    |
| `cookie:<name>=<value>` | The collector reads cookie `<name>`, URI-decodes it, and grants every category when the decoded value contains `<value>`. Otherwise every category is denied. This matches CMP strings, for example `cookie:OptanonConsent=C0002:1`. |

Cookie names may use letters, digits, `_`, `.`, and `-`; values may additionally use `:`, `%`, and `+`. Backoffice rejects anything else. A value that cannot be parsed is treated as `not_required`, so the domain keeps its current behavior.

**`not_required` is not a consent gate.** The persistent device identifier is written unless your page set `deviceId` to `denied`, and nothing waits for your banner. The extensions write it, so in this mode it applies from the moment they load: right away with `data-extensions="auto"`, the legacy URLs, or **Auto-load extensions**. The core alone never writes persistent storage. Pick `api` or a cookie mode when your visitors must decide first.

### Declaring the mode on the loader (optional)

The domain setting arrives with the first token. If your consent decision reaches the page by API, also declare the mode on the core tag so the client is strict from its first line, before that token returns:

```html
<script
	src="https://collect.noxtica.com/collector/noxtica-collector-core.js"
	data-site-key="pk_prod_your_site_key_here"
	data-consent-mode="api"
	data-auto-init
	data-auto-check-once
	async
></script>
```

Accepted forms are `data-consent-mode="api"`, `data-consent-mode="cookie:name"` or `data-consent-mode="cookie:name=value"`, and the shorthand `data-consent-cookie="name"` or `data-consent-cookie="name=value"`. Programmatic clients pass the same value:

```javascript
const client = NoxticaCollector.createClient({ siteKey: 'pk_prod_your_site_key_here', consentMode: 'api' });
```

A declaration can only make the client stricter. The domain setting stays authoritative for server enforcement, and a tag can never relax it. Without the declaration, a call such as `setConsent` made in the window before the token is announced with `mode: "not_required"`. Up to SDK 3.8.0 the same event then reports `api` only once the token arrives; from SDK 3.8.1 the client dispatches a second `noxtica:consent-changed` with `mode: "api"` when the token resolves, and `getConsent()` and the event detail carry `modeResolved` (`false` until then). If your bridge ever sends a partial object, or calls `loadExtensions()` before `setConsent`, declare the mode.

### Core and extensions in a gated mode

In the `api` and cookie modes, keep the core on every page and load the extensions only after the visitor accepts (see [Install](https://noxtica.com/docs/browser-runtime/#install-core-on-every-page-extensions-after-consent)). With the `api` mode, grant the categories and then load the extensions:

```javascript
const client = window.noxticaClient;
client.setConsent({ deviceId: 'granted', analytics: 'granted', replay: 'granted', behavioral: 'granted' });
await client.loadExtensions(); // resolves { ok: true } once the extensions are active
```

Each value is the string `'granted'` or `'denied'`; any other value, including `true` or `false`, throws a `TypeError`. Adding `data-extensions="auto"` to the core tag makes the core load the extensions on the first granted category instead.

### Consent API

With `data-auto-init`, the client is available as `window.noxticaClient`. Programmatic clients use the object returned by `createClient`.

- `client.setConsent({ analytics, replay, deviceId, behavioral })` sets each listed category to `'granted'` or `'denied'`. Omitted keys keep their current state.
- `client.setConsent('granted' | 'denied')` is the legacy form. It changes `analytics` only.
- `client.setReplayConsent(true | false)` changes `replay` only.
- `client.getConsent()` returns the current state: `{ mode, analytics, replay, deviceId, behavioral, privacySignal }`, where `privacySignal` is `'gpc'`, `'dnt'` or `null`.

Example wiring with a generic CMP callback (OneTrust- or Cookiebot-style). Map your CMP's purposes to Noxtica categories as your privacy team decides:

```javascript
const client = window.noxticaClient;
const state = (allowed) => (allowed ? 'granted' : 'denied');

cmp.onConsentChanged((choices) => {
	client.setConsent({
		analytics: state(choices.statistics),
		replay: state(choices.statistics),
		deviceId: state(choices.preferences),
		behavioral: state(choices.marketing),
	});
});
```

In cookie modes the collector reads the cookie when it starts and again on `visibilitychange` and `focus`, so a decision made in your banner applies when the visitor returns to the tab. A grant applies to all categories at once. A missing or non-matching cookie denies all categories and purges the persistent device stores.

### Verify your consent mode the way the browser sees it

The authoritative mode lives in the domain's tenant settings, not in your page code, so a settings change can alter behavior without any deploy on your side. Check what the browser actually receives:

- `window.noxticaClient.getConsent().mode` reports the effective mode: `not_required`, `api`, `cookie:<name>[=<value>]`, or `gcm`. Read it after the first `noxtica:collected` event, because until the token arrives the client does not know the domain's mode.
- `collectorConfig.consent` in the `POST /client/token` response (DevTools → Network) carries the server-side mode.

Make this a release check on the live page, with the banner still unanswered:

```javascript
// Expect your configured mode ('api' here). 'not_required' means the domain setting changed or the wrong domain is selected.
document.addEventListener('noxtica:collected', () => {
	console.assert(window.noxticaClient.getConsent().mode === 'api', 'Noxtica consent mode drifted');
});
```

With the mode `api` and nothing granted, you should see only the core script and `POST /client/token`, a `sessionStorage` token, and a `noxtica:collected` event with `skipped: 'consent_required'`. Before any decision every category must read `unknown` or `denied`, and `Object.keys(localStorage).filter((k) => k.startsWith('nox_'))` must be empty. Anything in `localStorage`, IndexedDB, or cookies before the visitor answers is a finding.

### Events and timing

Attach your listeners before the loader can run, and treat events as signals, not as data sources.

- **Listen early.** Put the `noxtica:collected` listener in an inline `<head>` script **before** the core tag. `checkOnce()` announces a visit once and does not re-collect inside its TTL, and an event that already fired is not replayed.
- **Deliver consent on `noxtica:ready`** (SDK 3.6.0 and later), which fires once per tag after `window.noxticaClient` exists. Back it with a bounded poll for older cores, and let the latest choice win.
- **Never trust `event.detail.client`.** Any script can dispatch a forged `noxtica:ready`. Use the event as a signal and read `window.noxticaClient`, which the core assigns before it dispatches.
- **Prefer deciding consent in a `noxtica:ready` handler, not in the pre-init queue (`noxtica('setConsent', …)`).** Before SDK 3.8.1 the queue replays every command in order, so a grant followed by a withdrawal still runs `loadExtensions()`. From SDK 3.8.1 queued consent updates are folded into one (the later key wins), a queued `loadExtensions` is dropped when all four categories end denied (`noxtica:extensions-failed` with `consent_missing`), and one `noxtica:consent-changed` fires. Use the queue for one-time declarations either way.
- **Decide "is Noxtica on this page" by host or build configuration,** not by a DOM attribute: a client-side locale switch or framework remount can clear attributes on `<html>`.

```html
<head>
	<script>
		document.addEventListener('noxtica:collected', (event) => {
			const result = event.detail;
			if (result.skipped === 'consent_required') return; // not an error: no device ID yet
			// Use result.fingerprintId only as a lookup handoff to your backend.
		});
	</script>
	<script src="https://collect.noxtica.com/collector/noxtica-collector-core.js" data-site-key="pk_prod_your_site_key_here" data-auto-init data-auto-check-once async></script>
</head>
```

```javascript
// Run when your consent choice is known; calls whenNoxticaReady once the client exists.
function whenNoxticaReady(callback, { timeoutMs = 15000 } = {}) {
	if (window.noxticaClient) return callback(window.noxticaClient);
	const started = Date.now();
	const poll = setInterval(() => {
		if (window.noxticaClient) { clearInterval(poll); callback(window.noxticaClient); }
		else if (Date.now() - started > timeoutMs) clearInterval(poll); // fail open: no client, no collection
	}, 250);
	document.addEventListener('noxtica:ready', () => { clearInterval(poll); if (window.noxticaClient) callback(window.noxticaClient); }, { once: true });
}
```

| Event                       | `event.detail`                                                                     | When                                                                                  |
| --------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `noxtica:ready`             | `{ client }`                                                                       | `data-auto-init` created the client (SDK 3.6.0+). The first check has not started.   |
| `noxtica:collected`         | the check result, or `{ success: false, skipped: 'consent_required', consentMode }` | After each check, and when a check is deferred until consent.                        |
| `noxtica:cache-hit`         | the same result with `fromCache: true`                                             | Right after `noxtica:collected` when the TTL served the stored result.               |
| `noxtica:consent-changed`   | the `getConsent()` snapshot                                                        | A category really changed.                                                            |
| `noxtica:extensions-loaded` | `{ message: 'attached', ok: true, loaded }`                                        | The extensions took over the client.                                                  |
| `noxtica:extensions-failed` | `{ message: 'not-loaded', ok: false, reason, code }`                               | A load attempt failed. A later `loadExtensions()` retries.                            |
| `noxtica:error`             | `{ source, message }`                                                              | A failure the SDK reported; also stored in `window.noxticaLastError`.                 |

The `extensions-*` event details are objects from SDK 3.8.0 and strings before it.

### Browser handoff sample

This sample loads the core tag and hands your own code one of three states: `received` with a device identifier, `invalid` when the result carries no identifier, or `unavailable` when the collector reports an error. The browser never receives a server credential. Replace `pk_example_replace_me` with the public Site Key of the exact origin.

```html
<script src="https://collect.noxtica.com/collector/noxtica-collector-core.js" data-site-key="pk_example_replace_me" data-extensions="auto" data-auto-init data-auto-check-once async></script>
<script>
  document.addEventListener('noxtica:collected', (event) => {
    const deviceId = event.detail?.fingerprintId;
    document.dispatchEvent(new CustomEvent('app:noxtica-evidence', {
      detail: deviceId ? { state: 'received', deviceId } : { state: 'invalid' },
    }));
  });

  document.addEventListener('noxtica:error', () => {
    document.dispatchEvent(new CustomEvent('app:noxtica-evidence', {
      detail: { state: 'unavailable' },
    }));
  });
</script>
```

The tag includes `data-extensions="auto"`; the attribute table under [Install: core on every page, extensions after consent](https://noxtica.com/docs/browser-runtime/#install-core-on-every-page-extensions-after-consent) says what it does, and loading the extensions never grants consent by itself. Send only the returned device identifier to your backend, as [Backend integration](https://noxtica.com/docs/backend-integration/#maintained-server-sample) shows.

### Loading extensions and its result

`loadExtensions()` never rejects. From SDK 3.8.0 it resolves `{ ok: true, loaded }` on success and `{ ok: false, reason, code }` on failure; up to 3.7.0 it resolved a boolean. An object is always truthy, so test the result, not its existence. Failures do not throw, so a retry guard that only clears on rejection never clears:

```javascript
let extensionsRequested = false;
async function requestExtensions() {
	if (extensionsRequested) return;
	extensionsRequested = true;
	const res = await window.noxticaClient.loadExtensions();
	const ok = res === true || res?.ok === true; // boolean up to 3.7, object from 3.8
	if (!ok) extensionsRequested = false; // allow a retry on the next consent signal
}
```

| `reason`             | Produced when                                                                                                         |
| -------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `consent_missing`    | You passed `{ requireConsent: true }` in a gated mode and no category is granted. Nothing is fetched.                 |
| `csp_blocked`        | The browser reported an enforced CSP violation for the script URL.                                                    |
| `integrity_mismatch` | A pinned file's bytes differ from its `integrity` value.                                                              |
| `network`            | An HTTP error or no response for the script (`http_<status>`, `fetch_failed`).                                        |
| `timeout`            | Neither a load nor an error event within 20 seconds. A later call retries.                                            |
| `already_loaded`     | A `<script>` for the extensions URL is already in the document but nothing registered.                                |
| `unknown`            | Everything else, such as a build mismatch.                                                                            |

An SRI-pinned core never falls back to unpinned code. An unpinned core falls back from the hashed file to the stable name. Treat `reason` as a hint for logging and `ok` as the contract.

### What runs without consent (core)

These parts run in every mode because they protect the page and its visitors:

- browser token issuance;
- `/client/submit` with the minimal sealed-runtime fingerprint;
- anti-automation counters (event counts and timing, no coordinates or key values);
- challenges that the server requests.

Until `deviceId` is granted, the device identifier stays in memory and `sessionStorage` and is not written to `localStorage`, IndexedDB, or cookies.

| Category     | What a grant enables                                                                                                                                   |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `analytics`  | Real-user monitoring (RUM), RUM batches and error detail, console log capture, the interaction tracker, and the durable client event buffer.         |
| `replay`     | Session replay recording and replay chunk upload.                                                                                                      |
| `deviceId`   | Persistent device storage (`localStorage`, IndexedDB, first-party cookie) and the server's persistent device-recognition token.                       |
| `behavioral` | Behavioral biometrics, pointer and touch tracks, geolocation, cookie contents, favicon supercookie detection, the extension probe, and the WebRTC probe. |

A category that is granted still depends on the tenant and domain features you have enabled; consent never switches on a feature your configuration leaves off.

### Server enforcement

When a domain's mode is anything other than `not_required`, the collector enforces consent on its side too. The loader adds an `nxc` query parameter naming the granted categories to each collector request; do not strip it in proxies or rewrite rules. The collector then:

- accepts and discards analytics payloads without `analytics` consent;
- accepts and discards replay payloads without `replay` consent;
- removes behavioral fields from `/client/submit` without `behavioral` consent;
- skips the persistent device-recognition token without `deviceId` consent.

A request without the parameter, for example from an older cached loader, counts as nothing granted. Discarded payloads still receive a normal success response, so the page never sees an error. Domains on `not_required` are not affected.

### Persistent device recognition switched off

If `persistent_device_recognition_enabled` is `false` for the domain, the collector never persists the device identifier in gated modes, even after `deviceId` is granted.

### Legal classification (not legal advice)

> **This table is informational and not legal advice; consult your DPO/counsel.** Classification depends on your jurisdiction, purposes, and configuration.

| Feature                                 | Data accessed                                                                        | Stored on device?                                                        | Purpose                     | Suggested category | Typical legal basis note                                                                                                             |
| --------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | --------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| Browser token                           | Site Key; the server sees IP address and request headers                             | `sessionStorage` token cache for the session                             | Security                    | core               | Security storage is often treated as strictly necessary under ePrivacy Art. 5(3); GDPR Art. 6(1)(f), fraud prevention (Recital 47). |
| Minimal sealed fingerprint (submit)     | Browser and device characteristics read inside the sealed runtime; proof of work    | `sessionStorage` status flag                                             | Fraud prevention            | core               | Reading device information is access under Art. 5(3); whether the strictly-necessary exemption applies needs assessment. GDPR Art. 6(1)(f). |
| Anti-automation counters                | Event counts, trusted-event flags, timing gaps, pressure; no coordinates or keys     | No                                                                       | Bot detection               | core               | GDPR Art. 6(1)(f); confirm the Art. 5(3) position with counsel.                                                                      |
| Server-requested challenge              | Loads Cloudflare Turnstile when the server asks for it                               | No by the collector; see Cloudflare's Turnstile documentation            | Security                    | core               | Security of the requested service; list Cloudflare as a processor or recipient.                                                     |
| Network and edge signals (server side)  | IP address, TLS and HTTP characteristics, rate limits                                | No                                                                       | Fraud prevention            | core               | No terminal access, so Art. 5(3) does not apply; GDPR Art. 6(1)(f).                                                                  |
| Cross-tab coordination                  | Lock and refresh timestamps                                                          | Yes, small `localStorage` keys, no identifier                            | Operation                   | core               | Functional state; strictly-necessary exemption commonly argued.                                                                      |
| Session device identifier               | Device identifier held for the current session                                       | Memory and `sessionStorage`                                              | Fraud prevention            | core               | Session-scoped storage; Art. 5(3) analysis still applies.                                                                            |
| Persistent device identifier            | Device identifier and an integrity canary                                            | Yes: `localStorage`, IndexedDB, first-party cookie (up to 400 days)      | Cross-session recognition   | deviceId           | Storage under Art. 5(3) usually needs consent unless strictly necessary; GDPR Art. 6(1)(a) or (f).                                  |
| RUM, RUM batches, error detail          | Performance and resource timing, redacted URLs, errors                               | No                                                                       | Analytics                   | analytics          | Art. 5(3) consent is typical; some regulators exempt narrow audience measurement.                                                   |
| Console log capture                     | Page `console` output                                                                | No                                                                       | Analytics and support       | analytics          | Consent is typical; logs may contain personal data your page writes.                                                                 |
| Interaction tracker                     | Clicks with target element type, scroll dwell, page views                            | No                                                                       | Analytics                   | analytics          | Art. 5(3) consent is typical.                                                                                                       |
| Durable client buffer                   | Queued analytics events                                                              | Yes, IndexedDB                                                           | Analytics delivery          | analytics          | Storage under Art. 5(3); follows the analytics purpose.                                                                             |
| Session replay and replay preloader     | Page structure, masked inputs, network and console metadata                          | Preloader: memory only; recorder: `sessionStorage` tab identifier        | User experience and support | replay             | Consent is typical (Art. 5(3) and GDPR Art. 6(1)(a)); masking reduces the risk of capturing special-category data.                  |
| Behavioral biometrics                   | Click, scroll, and key timing                                                        | No                                                                       | Fraud prevention            | behavioral         | Can be biometric data under GDPR Art. 4(14) and Art. 9 when used to identify a person; explicit consent, Art. 9(2)(a). US: BIPA. |
| Pointer and touch tracks                | Pointer and touch coordinates                                                        | No                                                                       | Fraud prevention            | behavioral         | GDPR Art. 9 risk as above; US: BIPA.                                                                                                 |
| Geolocation                             | Latitude and longitude, only when the browser permission is already granted          | No                                                                       | Fraud prevention            | behavioral         | Precise location is high-risk data; browser permission is not a GDPR legal basis.                                                  |
| Cookie contents                         | `document.cookie`                                                                    | No                                                                       | Fraud prevention            | behavioral         | Access under Art. 5(3); cookies may hold other vendors' identifiers.                                                                |
| Favicon supercookie detection           | Same-origin favicon cache                                                            | No                                                                       | Fraud prevention            | behavioral         | Access under Art. 5(3).                                                                                                             |
| Extension probe                         | Presence of browser extensions                                                       | No                                                                       | Fraud prevention            | behavioral         | Access under Art. 5(3); extensions can reveal sensitive traits (Art. 9 risk).                                                       |
| WebRTC probe                            | ICE candidates through a Google STUN server; public IP addresses are HMAC-hashed     | No                                                                       | VPN and proxy detection     | behavioral         | Third-party STUN contact; GDPR Art. 6(1)(f) with a balancing test.                                                                  |

Live assist is loaded separately and asks for its own consent; it is outside these categories.

## Protected actions

Protected actions keep bot and fraud protection on the steps attackers target, even for visitors who have not consented. Examples are `login`, `signup`, `checkout`, `kyc`, and `password_reset`. When one runs, the core executes the KHAN and Obsidian cores in minimal mode: they read device and browser characteristics only, store nothing on the device, and run no behavioral, replay, or analytics collection. Ordinary page views are never exempt.

**1. Declare** each action per domain in Script & Consent (Protected actions tab): a name (lowercase, up to 32 characters) and exactly one trigger, matched by `path` glob (`/login`, `/checkout/**`), by CSS `selector` of a form or button, or by a window `CustomEvent` name. A domain has at most 16 actions. Avoid catch-all paths such as `/**`: they would run the minimal check on every page view.

**2. Trigger** from the page, either on the form or in code:

```html
<form id="login" data-nox-protect="login" method="post" action="/session">…</form>
```

```javascript
const { requestId } = await window.noxticaClient.protect('login');
```

On a native, navigating form submit the core holds the submit for at most 6 seconds and adds a hidden `nox_request_id` field; a slow or failed check never blocks the visitor. For script-submitted forms see [Single-page apps and frameworks](https://noxtica.com/docs/browser-runtime/#single-page-apps-and-frameworks).

**3. Verify on your server.** Send the `requestId` to your backend with the protected request and redeem it from the backend, never from the browser. The call needs a Server API key (`sk_…`) with the `read:device` scope. The id is single-use inside a 300-second window.

```bash
curl -X POST "https://collect.noxtica.com/v1/protected-actions/verify" \
  -H "Authorization: Bearer sk_prod_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"requestId":"REQUEST_ID","action":"login","expectedDomain":"www.example.com"}'
```

| Status | Meaning                                                                                  |
| ------ | ---------------------------------------------------------------------------------------- |
| `200`  | Redeemed. The body carries `fingerprintId`, `verdict`, `score`, and `confidence`.        |
| `400`  | Malformed body: `invalid_body`, `invalid_request_id`, `invalid_action` or `invalid_expected_domain`. |
| `401`  | Missing or invalid key.                                                                  |
| `403`  | The key lacks the `read:device` scope.                                                   |
| `404`  | Unknown, expired (over 300 seconds), or another tenant's id.                             |
| `409`  | `already_consumed`: a replay inside the window. Refuse.                                  |
| `413`  | `payload_too_large`: the body is over 2048 bytes.                                        |
| `422`  | `action_mismatch` or `domain_mismatch`. The receipt is not consumed.                     |
| `429`  | Rate limit exceeded. Wait for `Retry-After`.                                             |

A missing `requestId` (timeout, blocked script) means "no client signal", not a pass: apply your own step-up. Use the `fingerprintId` from the verify response as the authoritative device identifier for that action, not an identifier the browser sent in a header. Up to SDK 3.8.0, two `noxtica:collected` events with different `fingerprintId` values could fire on one page (a minimal check by the core and a full one by the extensions when consent arrived while the token was still loading); from SDK 3.8.1 one page load produces one submit and one `noxtica:collected`. Identifiers can still differ between runtimes, so a client-sent value is not a source of truth.

## Single-page apps and frameworks

- **Load the core once**, in the app shell, never per route or per component. A route change does not need a new tag.
- **`data-auto-check-once` is TTL-cached.** `checkOnce()` respects the configured interval and announces a visit once, so a client-side navigation does not re-collect. Listen for `noxtica:collected` before the loader runs, as described in [Events and timing](https://noxtica.com/docs/browser-runtime/#events-and-timing).
- **Script-submitted forms** (React, SPA, `fetch`) cannot use the hidden `nox_request_id` field, because your own handler calls `preventDefault()`. A capture-phase listener starts the protected check before your handler and publishes the result on `form.dataset.noxRequestId`. Read it synchronously at the top of the handler, and call `protect()` synchronously to join the running check if it is not there yet:

```javascript
async function onSubmit(event) {
	event.preventDefault();
	const form = event.currentTarget;
	// Both lines run before the first await: the id is withdrawn when this handler returns.
	const ready = form.dataset.noxRequestId;
	const pending = ready ? null : window.noxticaClient.protect('login', { timeoutMs: 6000 });
	const requestId = ready ?? (await pending).requestId; // undefined on timeout or blocked script
	await fetch('/api/login', {
		method: 'POST',
		headers: { 'Content-Type': 'application/json', 'X-Request-Id': requestId ?? '' },
		body: JSON.stringify(payload),
	});
}
```

The id is attempt-scoped because it is single-use on the server: a retry after a wrong password runs a fresh check. `await noxticaClient.protect(name)` alone, without `data-nox-protect`, is the right tool for buttons, route changes, and flows without a `<form>`.

- **Angular and Zone.js.** The collector's own listeners, observers, and timers resolve the native functions that Zone.js leaves on the prototypes, so they do not trigger change detection. The session-replay recorder's internal listeners are third-party and are not patchable. If that matters, load the core outside the Angular zone:

```typescript
constructor(private zone: NgZone) {}
ngOnInit() {
	this.zone.runOutsideAngular(() => {
		const s = document.createElement('script');
		s.src = 'https://collect.noxtica.com/collector/noxtica-collector-core.js';
		s.dataset.siteKey = 'pk_prod_your_site_key_here';
		s.setAttribute('data-auto-init', '');
		document.head.appendChild(s);
	});
}
```

### Load timing and weight

A third-party script on every page needs a performance budget, and the load point is a measurement, not a default. Measured on 2026-10-24 at SDK 3.8.0 as served (3.8.1 bytes differ slightly): the core is about 460 KB raw (about 200 KB gzip) and the extensions about 730 KB raw (about 305 KB gzip). After consent the extensions start two WebAssembly modules and dozens of short-lived blob workers (38 in one measured integration). Measure your own page; sizes change with every release.

If the core competes with first paint or hydration, inject it after `load` and the first idle period instead of in `<head>`. Safari has no `requestIdleCallback`, so fall back to `setTimeout`:

```javascript
function loadNoxticaCore() {
	const s = document.createElement('script');
	s.src = 'https://collect.noxtica.com/collector/noxtica-collector-core.js';
	s.async = true;
	s.dataset.siteKey = 'pk_prod_your_site_key_here';
	s.setAttribute('data-auto-init', '');
	s.setAttribute('data-auto-check-once', '');
	document.head.appendChild(s);
}
const afterIdle = (fn) => ('requestIdleCallback' in window ? requestIdleCallback(fn, { timeout: 4000 }) : setTimeout(fn, 0));
if (document.readyState === 'complete') afterIdle(loadNoxticaCore);
else addEventListener('load', () => afterIdle(loadNoxticaCore), { once: true });
```

The core still parses as one main-thread task when it arrives. Keep the listener inline in `<head>` before this loader, keep the recorder head first if you use replay, and make sure the core is loaded before any protected action can fire.

## Storage and cookie disclosure

Name what the collector writes in your cookie and privacy notices. Persistent keys are written by the **extensions** only, only under the `deviceId` category, and never by the core; in a gated mode nothing persistent is written before `deviceId` is granted, and withdrawing it deletes the three device keys. `<sk>` is your Site Key.

| Name                               | Store                                                         | Lifetime                              | Category                | Written by                              |
| ---------------------------------- | ------------------------------------------------------------- | ------------------------------------- | ----------------------- | --------------------------------------- |
| `nox_fp_<sk>`                      | first-party cookie, `localStorage`, IndexedDB `nox_kv_<sk>`   | 400 days                              | `deviceId`              | Extensions                              |
| `nox_itp_canary_<sk>`              | first-party cookie, `localStorage`, IndexedDB `nox_kv_<sk>`   | 400 days                              | `deviceId`              | Extensions                              |
| `nox_tri_<sk>`                     | first-party cookie, `localStorage`, IndexedDB `nox_kv_<sk>`   | 400 days                              | `deviceId`              | Extensions                              |
| `nox_lock_<sk>`                    | `localStorage` (cross-tab lock)                               | at most 30 seconds, removed after each check | `deviceId`       | Extensions, only while storage is open  |
| `noxtica.session.<sk>.token`       | `sessionStorage` (token cache)                                | the browser session                   | none (security)         | Core and extensions                     |
| `noxtica.session.<sk>.protect.<action>` | `sessionStorage` (protected-action hand-off)             | the browser session                   | none (security)         | Core                                    |
| `noxtica.session.khanvm`, `.gpuvm` | `sessionStorage` (engine load status)                         | the browser session                   | none                    | Extensions                              |
| `__noxtica_khan_accel_v1`          | `sessionStorage` (capability cache)                           | the browser session                   | none                    | Extensions                              |
| `nx_replay_tab_id`, `nx_replay_session_v1` | `sessionStorage` (replay continuity)                  | tab session, ends after 30 minutes idle by default | `replay`   | Extensions                              |
| `nox_buf_<sk>`                     | IndexedDB (durable buffer for RUM and console-log events)      | undelivered events dropped after 72 hours | `analytics`         | Extensions                              |
| `_nox_test`, `cookietest`          | capability probes, created and removed in the same call       | none                                  | none                    | Extensions                              |

The three device cookies are set from script with `Path=/`, no `Domain` attribute (host-only), `SameSite=Lax`, and `Secure` on https, for 400 days. They are **not** `HttpOnly`: they are script-written by design, because the cookie is one redundant layer the SDK reads back to restore the other layers after a browser purges them. From SDK 3.8.1 the `nox_fp_<sk>` cookie holds only the state needed to recover the device identifier and its cache lifetime, as URI-encoded JSON: `{"_stateSchemaVersion":2,"deviceId":"…","lastSubmittedAt":"<ISO time>"}`. The last check result (score, risk level, confidence, flags) is written only to `localStorage` and IndexedDB (`nox_kv_<sk>`), never to the cookie; if only the cookie survives a browser purge, the identifier is restored and a cache hit reports no cached result until the next check. Before 3.8.1 the cookie also carried the last check result. Browsers may shorten script-written cookie lifetimes, so treat 400 days as the maximum.

## Check that it works

1. The core sets `window.noxticaClient`. Run `typeof window.noxticaClient` in the console.
2. The Network tab shows `POST /client/token` to your collector host with status 200. Filter by the collector host.
3. The `noxtica:collected` event fires (register your listener before the loader; afterwards read `window.noxticaResult`). In a gated mode before consent it carries `skipped: 'consent_required'`.
4. The Backoffice shows the visit: the domain page lists recent events, and live monitoring shows the device within a minute or two.
5. Server side, `GET https://collect.noxtica.com/v1/device/DEVICE_ID` with `Authorization: Bearer sk_prod_your_api_key` returns the record for the `fingerprintId` from the event. Handle `401`, `403`, `404`, and `429` explicitly.
6. Replay only: `window.__noxticaHead` is present, the replay policy is armed, and the `replay` category is granted.

| Symptom                                               | Likely cause                                                                                                              |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `window.__noxticaHead` appears only after first paint | Cloudflare Rocket Loader deferred the recorder head. Add `data-cfasync="false"` and keep it first and synchronous.        |
| Pinned tag blocked with an integrity error            | A stale pin: the file left the retention window or you copied a hash from a document. Re-copy from Script & Consent.      |
| `noxtica:collected` has `skipped: 'consent_required'` | The domain is in a gated mode and `setConsent` was never called, or `deviceId` is not granted.                            |
| `403` with `Origin mismatch` on `/client/token`       | The Site Key belongs to another origin. Use the key of the exact origin the page runs on. |
| Violations in the console                             | A CSP directive from the table above is missing. See [Content Security Policy](https://noxtica.com/docs/browser-runtime/#content-security-policy).                 |

## Release checks, testing and versions

**Guard the Site Key map as a production switch.** If your code selects the Site Key by host, that map is the only thing that turns Noxtica on. A change that removes a key switches it off silently. Add a post-deploy smoke test that the served HTML contains the install tag for each production host, give the files that hold the map and the consent bridge a CODEOWNERS entry, and keep one key per origin set.

**Test against a lab page, not production traffic.** Headless browsers are bot-scored and can be answered by a CDN challenge, so risk scores from headless runs are noise: never compare them across configurations. To test an enforcing CSP or consent flow on the real origin, serve a minimal page that contains your tag from the browser's own request interception, so the Site Key is accepted without sending traffic through your CDN. A spec outline:

- with consent withheld, the only collector traffic is the core script and `POST /client/token`, and storage holds only the `sessionStorage` token;
- after you deliver consent, the event sequence is `noxtica:consent-changed`, `noxtica:extensions-loaded`, then `noxtica:collected` with a `fingerprintId`;
- a blocked extensions script yields `noxtica:extensions-failed`, and the next consent signal retries.

**Versions.** The loader version appears in the manifest `version` field, the header comment of the script, and `window.noxtica.v` (SDK 3.7.0 and later). Behavior has changed between releases: `noxtica:ready` and the pre-init queue arrived in 3.6.0, the session API in 3.7.0, and the object result of `loadExtensions()` with object-valued extension events in 3.8.0. Re-run your release check after each collector release. Where your account has the typed `@noxtica/sdk` package, write against its typings rather than against prose.

## Browser responsibility

The browser loads the collector for the provisioned origin and public Site Key. It reports a collection result or an error state. If a result contains a device identifier, application code may pass that identifier to the customer backend for an authenticated lookup.

A server credential never belongs in browser JavaScript, HTML, a mobile application resource, a URL, or a client-visible log.

## Capability and consent boundary

Evidence availability depends on the current browser, tenant configuration, privacy signals, and consent state. JavaScript disabled or blocked means no new browser assessment. Reduced evidence, a suppressed browser-visible result, and a transport error are different states; none is automatically low risk.

Optional behavioral or replay capture requires its separately reviewed eligibility and consent or lawful-basis path. The public loader alone does not authorize collection beyond the configuration approved for the evaluation.

## Reliability checks

- Register both completion and error handling before relying on a result.
- Keep collection outside the page-rendering critical path.
- Preserve the normal customer journey when collection cannot run.
- Fail open with bounded waits. From consent to a collected result can take 8 to 11 seconds on a cold device; a budget of a second or two will usually expire on a first consented visit. Prefer the server-side verify response for the authoritative identifier over waiting in the browser.
- Send only the returned device identifier to your backend.
- Do not put identifiers, raw results, or credentials in URLs or optional analytics.
- Test the browser versions and privacy modes your own application supports.

## Next step

Follow [Backend Integration](https://noxtica.com/docs/backend-integration/) for authenticated lookup states and [Integration Flow](https://noxtica.com/docs/integration-flow/) for customer-owned policy rollout.

---

Source: https://noxtica.com/docs/sdk/script-attributes/
Markdown: https://noxtica.com/docs/sdk/script-attributes/index.md
Last updated: 2026-10-27

# Script attributes and client options

This page lists every setting you can put on the Noxtica script tag and every option you can pass to `createClient()` or `init()`, with the accepted values, the default and what each one changes. Use it when you edit the generated tag, wire the collector from your own code, or review a tag someone else pasted.

## What it is

Availability: Evaluation access. Availability depends on your plan, role and the modules enabled for your organisation.

The browser collector has two entry points:

- **The script tag.** The core script reads `data-*` attributes from its own tag when the page has loaded. Backoffice → Integrations & API → Script & Consent → Snippets generates the tag with your Site Key. Install and consent concepts stay on [Install and Browser Runtime](https://noxtica.com/docs/browser-runtime/).
- **Client options.** `window.NoxticaCollector.createClient(options)` takes the same ideas as an object, plus callbacks that an attribute cannot carry (`onChallenge`, `onBlock`). The typed `@noxtica/sdk` wrapper has an `init(config)` function that forwards a subset of these options. That wrapper is not installable from the public registry today; see [SDK family and availability](https://noxtica.com/docs/sdk/family/).

The loader reads the attributes once, when the tag initialises. Changing an attribute afterwards has no effect until the next page load. A value the loader cannot parse is ignored and never breaks collection.

## Prerequisites

- A domain with a Site Key. Backoffice → Domains lists the key; see [Domains, site keys and the install card](https://noxtica.com/docs/backoffice/domains/).
- A page served from the origin registered for that Site Key. A token request from another origin is refused with `403` and `{"error":"Origin mismatch"}`.
- Workspace admin access to Backoffice → Integrations & API → Script & Consent, if you want to copy the generated tag instead of typing it.
- The core script URL on your collector host: `https://collect.noxtica.com/collector/noxtica-collector-core.js`. The extensions script takes no attributes and no Site Key; it attaches to the core on the page.

## Steps

### 1. Start from the generated tag

Open Backoffice → Integrations & API → Script & Consent, pick the domain, and copy the core snippet from the **Snippets** tab. Two switches on that tab add attributes for you: **Add data-extensions="auto" to the core snippet** and **Add data-consent-mode="api" to the core snippet**.

```html
<script
	src="https://collect.noxtica.com/collector/noxtica-collector-core.js"
	data-site-key="pk_prod_your_site_key_here"
	data-auto-init
	data-auto-check-once
	async
></script>
```

Keep the file name. The loader binds a tag when its `src` contains `noxtica-collector` or `/noxtica.js` and the tag carries `data-auto-init`; a tag that misses either condition is ignored. This matters when you copy the script to your own path or serve it through a [first-party relay](https://noxtica.com/docs/sdk/csp-and-relay/).

### 2. Set the attributes you need

| Attribute | Accepted values | Default | Effect |
| --- | --- | --- | --- |
| `data-site-key` | Your Site Key | none, required | A tag without it is skipped: no client, no events. The key works on the origin registered for its domain. |
| `data-auto-init` | Boolean attribute | off | Creates the client for this tag, assigns `window.noxticaClient`, runs the `window.noxtica` command queue, then dispatches `noxtica:ready`. Without it the loader does nothing by itself. |
| `data-auto-check-once` | Boolean attribute | off | After `noxtica:ready`, runs `checkOnce()` once per page load and announces the result with `noxtica:collected`. Recommended. |
| `data-auto-collect` | Boolean attribute | off | Legacy. Runs `collectAndSubmit()` on every page load, without the cache. Ignored when `data-auto-check-once` is also present. |
| `data-ttl-seconds` | Positive integer | none | Cache window in seconds for the automatic check. Read together with `data-auto-check-once`; without that attribute it has no effect. Zero, negative and non-numeric values are ignored. |
| `data-check-interval-days` | Positive number | none | Cache window in days for every `checkOnce()` call of this client. Zero, negative and non-numeric values are ignored. |
| `data-api-url` | `https` URL, or any URL on `localhost` or `127.0.0.1` | `https://collect.noxtica.com` | Collector origin for the token, submit and visit calls. Any other value is ignored and a warning is logged. |
| `data-ingest-url` | `auto`, or an `https` URL (or a localhost URL) | `auto` | Origin for high-volume telemetry: RUM, RUM error detail, console logs, the client buffer, and the replay policy and upload calls. The interaction tracker stays on the collector. `auto` derives `https://ingest.noxtica.com` from the default collector host and keeps any other `data-api-url` host for telemetry too. An explicit URL wins; set it to the collector origin to keep telemetry on the collector. An invalid value is ignored and a warning is logged. |
| `data-consent-mode` | `api`, `cookie:<name>`, `cookie:<name>=<value>`, `gcm`, `not_required` | none | Declares the consent mode before the signed token arrives. A declaration can make the client stricter; it never relaxes the mode saved for the domain. See [Consent modes](https://noxtica.com/docs/sdk/consent/). |
| `data-consent-cookie` | `<name>` or `<name>=<value>` | none | Shorthand for `data-consent-mode="cookie:<name>"`. Ignored when `data-consent-mode` is present and valid. |
| `data-extensions` | `auto` | manual | `auto` makes the core load the extensions script itself. Any other value keeps the extensions manual, and overrides the automatic default of the legacy script URLs. The domain setting **Load the extensions script automatically once consent is granted (immediately in Not required mode)** still applies. |
| `data-log-level` | `silent`, `error`, `warn`, `info`, `debug` | see step 5 | Highest-precedence console log level. An invalid value is ignored. |
| `data-debug` | Boolean attribute | off | Legacy switch. Behaves like log level `debug` when no explicit level is set anywhere. |
| `data-debug-upload` | Boolean attribute | off | Diagnostic. Replay chunk and finalize uploads are captured on the page instead of being sent. Do not leave it on in production. |
| `integrity`, `crossorigin="anonymous"` | SRI hash, as generated | none | The pinned variant of the tag. See [Stable or pinned snippets](https://noxtica.com/docs/browser-runtime/#stable-or-pinned-snippets). |
| `async` | Boolean attribute | none | Lets the page render while the core loads. |

Two attributes go on your own forms, not on the script tag:

| Attribute | Where | Default | Effect |
| --- | --- | --- | --- |
| `data-nox-protect="<action>"` | A form, or a button or input inside one | none | Runs the protected-action check for the named action. The action must be declared for the domain. See [Protected actions](https://noxtica.com/docs/sdk/protected-actions/). |
| `data-nox-protect-timeout="<ms>"` | The same form | `6000` | How long a native form submit is held while the check runs. A value that is not a positive integer falls back to the default. |

### 3. Choose how often the page check runs

`checkOnce()` returns the cached result while the cache window is open and records a visit instead of collecting again. The loader picks the window in this order, and the earliest match wins:

1. `ttlSeconds` in the call. For the automatic check this is `data-ttl-seconds`.
2. `checkIntervalDays` in the call.
3. The client option `checkIntervalDays`, which `data-check-interval-days` sets.
4. The `checkIntervalDays` value in the domain policy delivered with the session token.
5. Seven days.

Call options for `checkOnce(options)`:

| Option | Default | Effect |
| --- | --- | --- |
| `ttlSeconds` | none | Cache window in seconds for this call. |
| `checkIntervalDays` | none | Cache window in days for this call. |
| `forceRefresh` | `false` | Clears the stored state and collects again. |
| `recordVisit` | `true` | Records a visit on a cache hit. With `false` the cached result comes back with `visitRecorded: false`. |
| `meta` | none | Metadata passed with the visit record. |

### 4. Create a client from code

Use `createClient` when a tag with `data-auto-init` does not fit, for example when your page decides at run time whether to start Noxtica. A client you create yourself does not set `window.noxticaClient`, does not dispatch `noxtica:ready` and does not read the command queue. Its results come back through the promises it returns.

```html
<script>
	const tag = document.createElement('script');
	tag.src = 'https://collect.noxtica.com/collector/noxtica-collector-core.js';
	tag.async = true;
	tag.onload = () => {
		const client = window.NoxticaCollector.createClient({
			siteKey: 'pk_prod_your_site_key_here',
			consentMode: 'api',
			logLevel: 'silent',
		});
		client.checkOnce().then((result) => console.log(result.success));
	};
	document.head.appendChild(tag);
</script>
```

`createClient` throws `NoxticaCollector: siteKey is required` when it finds no Site Key, either in the `siteKey` option or on a collector tag with `data-site-key`.

| Option | Type and default | Effect |
| --- | --- | --- |
| `siteKey` | string | Your Site Key. Falls back to the `data-site-key` of a collector tag on the page. |
| `apiUrl` | `https` URL, default `https://collect.noxtica.com` | Collector origin. |
| `ingestUrl` | URL or `'auto'`, default `'auto'` | Telemetry origin; same rules as `data-ingest-url`. |
| `mode` | `'max'` (default) or `'lite'` | `max` collects the full signal set. `lite` skips the collectors that belong to `max` mode. Protected actions always run in minimal mode. |
| `checkIntervalDays` | number | Client-level cache window. |
| `signatureMode` | `'require'` (default), `'warn'`, `'disabled'` | What the client does when a signed server response is missing or altered. `require` rejects it, `warn` logs and continues, `disabled` skips the check. An unknown value falls back to `require`. Keep `require`. |
| `accountId` | string, up to 256 characters | Your own end-user account id, sent with the next submit. Use an opaque id, not an e-mail address. `client.setAccountId(id)` sets it later. |
| `consentMode` | `'api'`, `'cookie:<name>'`, `'cookie:<name>=<value>'`, `'gcm'`, `'not_required'` | Same as `data-consent-mode`. |
| `extensions` | `'auto'` | Same as `data-extensions="auto"`. |
| `logLevel` | `'silent'`, `'error'`, `'warn'`, `'info'`, `'debug'` | Same as `data-log-level`, one precedence step lower. |
| `debug` | boolean | Legacy form of log level `debug`. |
| `debugUploads` | boolean | Same as `data-debug-upload`. |
| `onChallenge` | function | Called with `{ status, method }` while the server asks for a step-up challenge. Advisory. |
| `onBlock` | function | Called with `{ status, mode }` when the page enforces a server block. Advisory. |
| `release`, `buildId`, `subjectHandle` | strings | Labels for browser error detail. They take effect when the extensions are loaded. See [Browser errors, console logs and source maps](https://noxtica.com/docs/observability/errors-and-source-maps/). |

The wrapper's `init(config)` accepts `siteKey`, `apiUrl`, `ingestUrl`, `mode`, `checkIntervalDays`, `signatureMode`, `accountId`, `debug`, `logLevel`, `onChallenge`, `onBlock`, `release`, `buildId`, `subjectHandle` and `observability`, plus options that are specific to the wrapper:

| Wrapper option | Default | Effect |
| --- | --- | --- |
| `script` | `'core'` | `'core'` injects the core script. `'combined'` injects the legacy combined script. |
| `extensions` | `'manual'` | `'manual'` waits for `loadExtensions()`. `'auto'` lets the core load them. `'never'` makes `loadExtensions()` reject, and cannot be combined with `script: 'combined'`. |
| `scriptUrl`, `pinnedLoader` | none | Inject a pinned core: set `scriptUrl` to the hashed file name from the collector manifest and `pinnedLoader.integrity` to its hash. The URL must be `https` on the default collector origin or your own `apiUrl` origin. |

`init()` does not pass `consentMode` to the loader. To declare a mode, put `data-consent-mode` on the tag or call `createClient` directly.

### 5. Set the log level

The loader writes nothing to the console by default. Four sources can change that. The highest one that holds a valid value wins:

1. The `data-log-level` attribute on the script tag.
2. The `logLevel` option of `createClient()` or `init()`, or `NoxticaCollector.setLogLevel(level)`.
3. The domain setting. In Backoffice open Domains, open the domain, then Configuration → **Client log level** → **Console log level**. The choices are SDK default, Silent, Error, Warn, Info and Debug. The value arrives with each session token, so a change applies from the next token.
4. The SDK default: silent, unless `data-debug`, the `debug` option or `window.NOXTICA_DEBUG = true` turns on `debug`.

`silent` means no console output from any Noxtica code path. Read the effective level with `window.NoxticaCollector.getLogLevel()`.

A `data-log-level` attribute applies before the loader reads the other attributes, so it also reveals the warnings from step 2, such as a rejected `data-api-url`. The domain setting arrives later, with the token.

## Verify it works

Run these in the browser console on a page that carries the tag:

```javascript
typeof window.noxticaClient;            // 'object' when data-auto-init bound the tag
window.noxticaClient.siteKey;           // your Site Key
window.noxticaClient.apiUrl;            // the collector origin in use
window.noxticaClient.ingestUrl;         // the telemetry origin in use
window.NoxticaCollector.VERSION;        // the loader version, for example '3.8.1'
window.noxtica.v;                       // the same version, published for the duplicate-tag guard
window.NoxticaCollector.getLogLevel();  // the effective log level
```

In DevTools → Network you see `POST /client/token` on the collector host with status `200`. After consent, when the extensions run, and with `data-ingest-url` left at `auto` on the default collector, telemetry requests go to `ingest.noxtica.com`.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| `window.noxticaClient` is undefined and no `noxtica:*` event fires | The tag lacks `data-auto-init` or `data-site-key`, or the `src` file name contains neither `noxtica-collector` nor `/noxtica.js` | Add the attributes, or keep the original file name when you copy or proxy the script. |
| `data-api-url` has no effect | The value is not `https` and not on `localhost` or `127.0.0.1`, or it is not a valid URL | Use an `https` URL. The warning appears at log level `warn` or higher. |
| Telemetry still goes to the collector host | `data-ingest-url` equals the collector origin, or `data-api-url` points at a host other than the default collector | Set `data-ingest-url` to the telemetry origin you want. |
| Changing an attribute in the console changes nothing | The loader read the attributes when the tag initialised | Reload the page, or create a client from code. |
| `getConsent().mode` differs from `data-consent-mode` | The mode saved for the domain wins once the token arrives | See [Consent modes](https://noxtica.com/docs/sdk/consent/). |
| `NX001: already loaded` in the console | A second core or combined tag is on the page, for example one pasted by hand and one from a tag manager | Remove the extra tag. The initial one keeps running. |
| `NoxticaCollector: siteKey is required` | `createClient` found no Site Key | Pass `siteKey`, or keep `data-site-key` on a collector tag. |
| `403` with `Origin mismatch` on `/client/token` | The page origin is not the origin registered for the Site Key | Use the key of the exact origin the page runs on. |

## Related

- [Install and Browser Runtime](https://noxtica.com/docs/browser-runtime/): install, pinned tags, CSP and the check list.
- [Client API, events and the command queue](https://noxtica.com/docs/sdk/client-api/): the methods and events these attributes feed.
- [Consent modes, GPC and Google Consent Mode](https://noxtica.com/docs/sdk/consent/): what `data-consent-mode` and `data-extensions` do at run time.
- [Browser SDK troubleshooting](https://noxtica.com/docs/sdk/troubleshooting/): a symptom table across the whole SDK.
- [SDK Changelog](https://noxtica.com/docs/changelog/): which release added or changed each setting.

---

Source: https://noxtica.com/docs/sdk/client-api/
Markdown: https://noxtica.com/docs/sdk/client-api/index.md
Last updated: 2026-10-27

# Client API, events and the command queue

This page is the reference for what the core script puts on your page: the globals, the client methods, the events on `document`, and the `window.noxtica(...)` command queue. Use it when you wire a consent banner, react to a step-up challenge, or queue calls before the script has loaded.

## What it is

Availability: Evaluation access. Availability depends on your plan, role and the modules enabled for your organisation.

A core tag with `data-auto-init` builds one client for the page. The client, the events and the command queue exist on tags that carry `data-auto-init`. A client you create with `NoxticaCollector.createClient()` returns its results through promises and does not fire `noxtica:ready`. See [Script attributes and client options](https://noxtica.com/docs/sdk/script-attributes/).

Until the extensions script attaches, the core runs a reduced lane. When the extensions attach, every public method of the client delegates to the extensions runtime; the core keeps `loadExtensions`, `getExtensionsState` and `destroy`. Loading the extensions never grants consent; see [Consent modes](https://noxtica.com/docs/sdk/consent/).

## Prerequisites

- The core tag with `data-site-key` and `data-auto-init`, as generated by Backoffice → Integrations & API → Script & Consent → Snippets.
- Your listeners registered before the core tag runs. Put them in an inline script in `<head>` above the tag. An event that already fired is not replayed.
- Your own consent flow, if the domain uses the `api` mode: your page calls `setConsent`. See [Consent modes](https://noxtica.com/docs/sdk/consent/).

## Steps

### 1. Read the page globals

| Global | What it holds |
| --- | --- |
| `window.NoxticaCollector` | The loader object: `VERSION`, `SCHEMA_VERSION`, `SDK_VERSIONS`, `createClient(options)`, `autoDiscoverSiteKey()`, `setApiUrl(url)`, `setIngestUrl(url)`, `setLogLevel(level)`, `getLogLevel()`, and on the core script `BUNDLE` (`'core'`), `registerExtensions(ext)` and a static `loadExtensions()`. `setApiUrl` and `setIngestUrl` take effect for clients created afterwards and reject a URL that is not `https` (localhost excepted). Other members of the object are diagnostics, not part of the supported surface. |
| `window.noxticaClient` | The client of the `data-auto-init` tag. Properties `siteKey`, `apiUrl` and `ingestUrl`. |
| `window.noxtica` | The command function (step 4). `window.noxtica.v` holds the loader version once a core or combined script has claimed the page. |
| `window.noxticaResult` | The last result announced with `noxtica:collected`. |
| `window.noxticaLastError` | The last error the loader reported: `{ source, message, time }`. The message is cut to 200 characters. |

### 2. Call the client methods

**Page check and state**

| Method | Returns | Notes |
| --- | --- | --- |
| `checkOnce(options)` | Promise of a result (step 5) | Cache-aware page check. Options are in [Script attributes and client options](https://noxtica.com/docs/sdk/script-attributes/). In a gated consent mode without a `deviceId` grant it resolves a `skipped` result and runs again when the grant arrives. |
| `collectAndSubmit()` | Promise of a result | Collects and submits on every call, without the cache. |
| `collect()`, `submit(payload)`, `visit(deviceId, meta)` | Promises | Building blocks of the two methods above. Prefer `checkOnce`. |
| `getToken()` | Promise of the session token string, or `null` | Fetches or refreshes the token without submitting. |
| `getPolicy()` | Object or `null` | The policy delivered with the session token. |
| `getStoredState()`, `clearStoredState()` | State object or `null`; nothing | Read or delete the cached device state that `checkOnce` uses. |
| `getEffectiveTtlSeconds(options)` | Number | The cache window in seconds that a call with these options would use. |

**Lifecycle**

| Method | Effect |
| --- | --- |
| `pause()`, `resume()` | `pause` holds replay flushing, mutation processing and tracker and RUM uploads without ending anything; `resume` drains what was held. |
| `stop()`, `start()` | `stop` tears the lanes down but keeps consent state and device storage; `start` re-arms them. |
| `destroy()` | Stops timers and lanes and makes this client inert. Create a new client to continue. |

**Consent and extensions**

| Method | Effect |
| --- | --- |
| `setConsent(update)` | `update` is `{ analytics, replay, deviceId, behavioral }` with values `'granted'` or `'denied'`, or the legacy string `'granted'` / `'denied'`, which sets the `analytics` category. Any other shape throws a `TypeError`. |
| `getConsent()` | `{ mode, modeResolved, analytics, replay, deviceId, behavioral, privacySignal }`. |
| `enableGoogleConsentMode()` | Turns on the Google Consent Mode v2 bridge. |
| `setReplayConsent(boolean)` | Legacy switch for the `replay` category. |
| `getReplayConsentState()` | `UNINITIALIZED`, `DISABLED`, `AWAITING_CONSENT`, `DENIED` or `POLICY_READY`. |
| `getReplayRecorderState()` | `idle`, `loading`, `active`, `stopped` or `error`. |
| `loadExtensions(options)` | Promise of `{ ok: true, loaded }` or `{ ok: false, reason, code, … }`. Never rejects. See [Loading extensions and its result](https://noxtica.com/docs/browser-runtime/#loading-extensions-and-its-result). |
| `getExtensionsState()` | `'not-loaded'`, `'attached'`, or `'built-in'` on the legacy combined script. |

**Protected actions, identity and events**

| Method | Effect |
| --- | --- |
| `protect(name, { timeoutMs })` | Runs the protected-action check and resolves the result with a `requestId`. See [Protected actions](https://noxtica.com/docs/sdk/protected-actions/). |
| `setAccountId(id)` | Links the device to your own account id on the next submit. Non-string, empty and values over 256 characters are ignored. Use an opaque id. |
| `identify(id, { hint })` | Session identity: Noxtica receives a hash of the id and a two-character hint. Not the same as `setAccountId`. The typed wrapper calls this `identifySession()` and uses `identify()` for the account id. |
| `setTag(key, value)`, `event(name, value)`, `getMetadata(callback, options)`, `upgrade(reason)` | Session tags, timeline markers, the ids that join Noxtica data to yours, and starting replay with a reason. Limits and consent rules are on [Custom events, session tags and request tracing](https://noxtica.com/docs/observability/events-and-tracing/). `upgrade` returns `started`, `already_recording`, `pending_consent` or `refused`. |
| `track(name, properties)` | Custom application event. Names and properties that the domain allow-list does not list are dropped. |
| `withRequestSpan(url, callback)`, `spanFetch(url, init)` | W3C trace context for one request, for origins on the domain's trace allow-list. |
| `loadReplayPlugins()`, `loadReplayAssist()`, `debug({ uploads })` | Replay add-ons and the upload debug switch. See [Session replay](https://noxtica.com/docs/observability/session-replay/). |

The client object has more members, such as tracker and token-refresh controls. They are internal and not supported.

### 3. Listen to events

All events are dispatched on `document` with a `CustomEvent`. Register the listeners in `<head>` before the core tag:

```html
<script>
	document.addEventListener('noxtica:collected', (event) => {
		if (event.detail.skipped === 'consent_required') return; // not an error
		// Hand event.detail.fingerprintId to your backend as a hint, not as an identity.
	});
	document.addEventListener('noxtica:error', (event) => {
		console.warn('Noxtica reported', event.detail.source, event.detail.message);
	});
	document.addEventListener('noxtica:challenge', (event) => {
		// event.detail: { status: 'started' | 'solved' | 'failed' | 'unsupported', method: 'gpu-pow' | 'turnstile' }
	});
	document.addEventListener('noxtica:block', (event) => {
		// event.detail: { status: 'blocked' | 'redirected' | 'failed', mode: 'overlay' | 'redirect' }
	});
</script>
```

| Event | `event.detail` | When |
| --- | --- | --- |
| `noxtica:ready` | `{ client }` | The `data-auto-init` tag created the client and ran the command queue. The automatic check has not started. Fires once per tag. |
| `noxtica:collected` | The check result, or `{ success: false, skipped: 'consent_required', fromCache: false, consentMode }` | After the automatic check, a check that waited for consent, and a queued `checkOnce`. Also sets `window.noxticaResult`. |
| `noxtica:cache-hit` | The same result with `fromCache: true` | Right after `noxtica:collected` when the cache answered. |
| `noxtica:consent-changed` | The `getConsent()` snapshot | A consent category really changed, or the signed mode differs from the page's declaration once the token arrives. |
| `noxtica:extensions-loaded` | `{ message: 'attached', ok: true, loaded }` | The extensions took over the client. |
| `noxtica:extensions-failed` | `{ message: 'not-loaded', ok: false, reason, code, … }` | A load attempt failed, or a queued `loadExtensions` was dropped because every category is denied. |
| `noxtica:error` | `{ source, message, time }` | The loader reported a failure. Known sources include `Auto-init failed`, `Auto-check-once failed`, `Auto-collect failed`, `Deferred page check failed` and `noxtica("<command>") failed`. Also stored in `window.noxticaLastError`. |
| `noxtica:challenge` | `{ status, method }` | The server asked the browser for a step-up challenge. `status` is `started`, `solved`, `failed` or `unsupported`; `method` is `gpu-pow` or `turnstile`. Advisory: the server decides. |
| `noxtica:block` | `{ status, mode }` | The page enforced a server block. `status` is `blocked`, `redirected` or `failed`; `mode` is `overlay` or `redirect`. Advisory. |
| `noxtica:protected` | `{ action, requestId, success, source, reason, timedOut? }` | A protected-action check for a form or control settled. Dispatched on that element; it bubbles. `source` is `warm`, `click` or `submit`. |
| `noxtica:debug-upload` | The captured upload | Fires with `data-debug-upload` or `debug({ uploads })` and in no other case. |

`noxtica:challenge` and `noxtica:block` fire when the server issues a challenge or a block for the visit, and not otherwise. Whether your domain can issue them depends on your configuration. The page acts on a block directive when the signed result verifies and carries the same block id, so a forged directive does nothing.

With `createClient` options `onChallenge` and `onBlock` you get the same details through callbacks. A callback that throws never breaks collection.

`noxtica:extensions-*` details were strings before SDK 3.8.0. Read `detail.message` for the old value.

### 4. Queue calls before the script loads

The command queue follows the gtag pattern. Define the stub above the core tag, then call it:

```html
<script>
	window.noxtica = window.noxtica || function () { (window.noxtica.q = window.noxtica.q || []).push(arguments); };
	noxtica('consent', 'gcm');
	noxtica('set', 'plan', 'pro');
</script>
<script
	src="https://collect.noxtica.com/collector/noxtica-collector-core.js"
	data-site-key="pk_prod_your_site_key_here"
	data-auto-init
	data-auto-check-once
	async
></script>
```

An array assigned to `window.noxtica` also works as a stub. The core replays the queued calls in order against the initial client it creates, then replaces the stub with a live function. Later calls, and a stub reference you kept, run at once and return the method's result.

| Command | Arguments | Runs |
| --- | --- | --- |
| `setConsent` | update object, or `'granted'` / `'denied'` | `client.setConsent` |
| `consent` | `'gcm'`, or an update object | `enableGoogleConsentMode()` or `setConsent` |
| `loadExtensions` | options | `client.loadExtensions` |
| `protect` | name, options | `client.protect` |
| `checkOnce` | options | `client.checkOnce`; the result is announced with `noxtica:collected` |
| `set` | key, value or list of values | `client.setTag` |
| `identify` | id, `{ hint }` | `client.identify` (session identity) |
| `event` | name, value | `client.event` |
| `metadata` | callback, `{ wait, recall }` | `client.getMetadata` |
| `upgrade` | reason | `client.upgrade` |
| `pause`, `resume`, `stop`, `start` | none | the lifecycle methods |

These are the 14 commands. Behaviour to rely on:

- An unknown command logs a warning and does nothing. A command that fails reports `noxtica:error` and never throws.
- Queued `setConsent` and `consent` updates are folded into one update, applied where the earliest of them stood (a later key wins), so you get one `noxtica:consent-changed`. A queued `loadExtensions` is dropped when the folded state denies all four categories. This applies to loader 3.8.1 and later; earlier loaders replayed every call in order.
- If `window.noxtica` is a plain object without a `q` array, the loader leaves it untouched and the commands are unavailable.
- Deciding consent in a `noxtica:ready` handler is more robust than queuing it. See [Events and timing](https://noxtica.com/docs/browser-runtime/#events-and-timing).

### 5. Read the `checkOnce` result

| Field | Present when | Meaning |
| --- | --- | --- |
| `success` | always | `true` when the check or the cache hit succeeded. |
| `fingerprintId` | success | Device id as the browser sees it. A hint: the core and the extensions runtimes can mint different ids for one browser. The authoritative id is the one from [the server-side verify call](https://noxtica.com/docs/sdk/protected-actions/). |
| `fromCache` | always | `true` when the cache answered. |
| `cachedResult` | cache hit | `{ score, risk_level, confidence, flags }` from the last check, or `null` when the cookie is the sole storage that survived. |
| `daysSinceSubmit`, `nextSubmitIn` | cache hit | Days since the last submit and days left in the window. |
| `visitRecorded` | `recordVisit: false` | `false`. |
| `acquiredFromAnotherTab` | another tab ran the check | `true`. A cross-tab lock keeps tabs from submitting twice; it times out after 30 seconds. |
| `forceRefreshed` | `forceRefresh: true` | `true`. |
| `skipped`, `consentMode` | gated mode without a `deviceId` grant | `skipped: 'consent_required'`; no `fingerprintId`. |

A numeric `score`, `risk_level` and `confidence` may be absent when the server withholds them. Treat a missing score as unknown, never as zero.

## Verify it works

Open the console on a page that has the tag and consent decided:

```javascript
window.noxticaClient.getConsent();        // { mode, modeResolved, analytics, replay, deviceId, behavioral, privacySignal }
window.noxticaClient.getExtensionsState(); // 'not-loaded' before the extensions attach, 'attached' after
window.noxticaResult;                      // the last result announced with noxtica:collected
window.noxtica.v;                          // the loader version
await window.noxticaClient.getToken();     // a token string once /client/token succeeded
```

Add a temporary listener for each event in step 3 and reload. A healthy consented page logs `noxtica:ready`, then `noxtica:consent-changed` and `noxtica:extensions-loaded` after your consent call, then `noxtica:collected`.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| A listener never fires | It was registered after the event, or the tag lacks `data-auto-init` | Move the listener into `<head>` above the tag. For a late page, read `window.noxticaClient` and `window.noxticaResult` directly. |
| `window.noxtica(...)` does nothing | `window.noxtica` is a plain object, or the tag lacks `data-auto-init` | Define the stub as a function or an array, and keep `data-auto-init`. |
| `setConsent` throws `NoxticaCollector.setConsent requires granted, denied, or { analytics, replay, deviceId, behavioral }` | The argument is `true`, `false` or another shape | Pass the strings `'granted'` or `'denied'`. |
| `setConsent` throws `unknown consent category` | A key other than `analytics`, `replay`, `deviceId`, `behavioral` | Remove the key. |
| `noxtica:collected` carries `skipped: 'consent_required'` | The domain is in a gated mode and `deviceId` is not granted | Call `setConsent({ deviceId: 'granted' })` after the visitor agrees. The check then runs again on the same page. |
| `protect()` resolves `error: 'undeclared_protected_action'` | The action name is not declared for the domain | Declare it in Script & Consent → Protected actions. |
| `identify()` did not link my account | `identify` is the hashed session identity | Use `setAccountId(id)`. |
| Two `noxtica:collected` events with different ids | A loader older than 3.8.1 | See [SDK Changelog](https://noxtica.com/docs/changelog/). Take the id from the server-side verify call. |

## Related

- [Script attributes and client options](https://noxtica.com/docs/sdk/script-attributes/): the options that configure the client.
- [Consent modes, GPC and Google Consent Mode](https://noxtica.com/docs/sdk/consent/): categories, precedence and the Google bridge.
- [Protected actions](https://noxtica.com/docs/sdk/protected-actions/): `protect()`, `noxtica:protected` and the server check.
- [Install and Browser Runtime](https://noxtica.com/docs/browser-runtime/): events and timing, extension load reasons.
- [Custom events, session tags and request tracing](https://noxtica.com/docs/observability/events-and-tracing/): the session API in depth.
- [Browser SDK troubleshooting](https://noxtica.com/docs/sdk/troubleshooting/): symptoms across the SDK.

---

Source: https://noxtica.com/docs/sdk/single-page-apps/
Markdown: https://noxtica.com/docs/sdk/single-page-apps/index.md
Last updated: 2026-10-27

# Single-page apps, frameworks and tag managers

A single-page app changes the URL without loading a new document, a framework re-renders its own markup, and a tag manager injects scripts on its own schedule. This page shows what the collector does in those setups and what you do to keep one clean install.

## What it is

Availability: Evaluation access. Availability depends on your plan, role and the modules enabled for your organisation.

The collector is a plain script. It needs one core tag per document, a Site Key that matches the page origin, and a `window` and `document` to run in. It does not depend on your framework. The core script watches client-side navigation through the History API when a protected action matches a page path, and it does nothing else on a route change. The page check belongs to the document, not to the route.

The typed `@noxtica/sdk` wrapper has React, Next.js and Vue helpers in its source. That package is not installable from the public registry today (the registry answered `E404` on 2026-10-27), so this page gives no install command for it. Ask your account team for access; see [SDK family and availability](https://noxtica.com/docs/sdk/family/). Every recipe below works with the script tag alone.

## Prerequisites

- A Site Key for the origin your app is served from. Staging and production origins have separate keys. A key used on another origin gets `403` with `Origin mismatch`.
- The core tag from Backoffice → Integrations & API → Script & Consent → Snippets. See [Install and Browser Runtime](https://noxtica.com/docs/browser-runtime/).
- Your consent mode decided. See [Consent modes](https://noxtica.com/docs/sdk/consent/).
- For tag managers: the right to publish tags that run on every page of the site.

## Steps

### 1. Load the core once, in the app shell

Put the tag in the document that the app mounts into: `index.html`, the root layout, or the theme's `<head>`. Do not add it per route or per component.

```html
<head>
	<script>
		document.addEventListener('noxtica:collected', (event) => {
			if (event.detail.skipped === 'consent_required') return; // not an error
			// Use event.detail.fingerprintId as a hint for your backend.
		});
	</script>
	<script
		src="https://collect.noxtica.com/collector/noxtica-collector-core.js"
		data-site-key="pk_prod_your_site_key_here"
		data-auto-init
		data-auto-check-once
		async
	></script>
</head>
```

Register your `noxtica:*` listeners in a script that runs before the tag. An event that already fired is not replayed. If your framework cannot run code before the tag, queue calls with the `window.noxtica` stub instead, and read `window.noxticaClient` and `window.noxticaResult` after load. See [Client API, events and the command queue](https://noxtica.com/docs/sdk/client-api/).

If the core competes with the initial render or hydration, inject it after the `load` event and the next idle period. A ready-made snippet is in [Load timing and weight](https://noxtica.com/docs/browser-runtime/#load-timing-and-weight).

### 2. Pick a framework recipe

| Setup | What you do |
| --- | --- |
| Vite, Create React App or any bundler with an `index.html` | Add the tag from step 1 to `index.html`. |
| Vue | Add the tag to `index.html`. |
| Next.js, App Router | Render the tag with `next/script` in the root layout. |
| Angular | Add the tag to `index.html`. To keep the collector's timers out of change detection, load it outside the Angular zone; see [Single-page apps and frameworks](https://noxtica.com/docs/browser-runtime/#single-page-apps-and-frameworks). |
| Server-side rendering | Emit the tag in the HTML. The loader does nothing without a `document`, so a server render is not affected. Do not import or call the collector in server code. |

For Next.js, the markup below is what the wrapper's `NoxticaScript` component renders, taken from the wrapper source. `afterInteractive` is its default strategy. Test it in your own app:

```tsx
// app/layout.tsx
import Script from 'next/script';

export default function RootLayout({ children }: { children: React.ReactNode }) {
	return (
		<html lang="en">
			<body>
				{children}
				<Script
					src="https://collect.noxtica.com/collector/noxtica-collector-core.js"
					strategy="afterInteractive"
					data-site-key="pk_prod_your_site_key_here"
					data-auto-init=""
					data-auto-check-once=""
				/>
			</body>
		</html>
	);
}
```

The wrapper's helpers, for accounts that have the package:

| Helper | What it does, from the 0.3.0 source |
| --- | --- |
| `NoxticaProvider`, `useNoxtica` (React) | The provider creates one client in an effect, so it runs in the browser and not on the server. `useNoxtica()` returns `{ client, loading, error }`. The provider destroys its client when it unmounts. |
| `useVerdict` (React) | Requests a verdict when the client is ready, unless you pass `auto: false`. Returns `{ verdict, loading, error, refresh }`. |
| `NoxticaScript` (Next.js) | Renders the tag through `next/script` with `data-site-key`, `data-auto-init` and `data-auto-check-once`. Options: `apiUrl`, `ingestUrl`, `scriptUrl`, `script`, `extensions`, `auto`, `checkIntervalDays`, `debug`, `logLevel`, `strategy`. It has no consent-mode option. |
| `createNoxtica`, `useNoxtica` (Vue 3) | A plugin and a composable. They return `client`, `loading`, `error`, `verdict`, `getVerdict` and `identify`. The plugin stays inert during server rendering. |

The wrapper's `init()` rejects outside a browser. Guard shared code with `isBrowser()`.

### 3. Handle route changes

A route change does not run a new page check. `data-auto-check-once` runs `checkOnce()` once for the document, and the cache answers later calls. What you can rely on:

- Protected actions that match a **Page path** run on the initial load and again when the History API changes the URL (`pushState`, `replaceState`, `popstate`). The core shares one wrapper per page and restores the original methods when no subscriber is left. It leaves your own wrappers in place.
- Calling `checkOnce()` on every route is allowed. With the default `recordVisit: true`, a cache hit records a visit with the collector, so each call sends a request. Pass `{ recordVisit: false }` when you do not want that.
- Call `checkOnce({ forceRefresh: true })` or `collectAndSubmit()` when a flow needs a fresh check, and not otherwise. Both collect again and submit.
- For application events and session tags, use `track`, `event` and `setTag` from [Custom events, session tags and request tracing](https://noxtica.com/docs/observability/events-and-tracing/).

Do not decide whether Noxtica is on a page from an attribute that your framework renders. A locale switch or a remount can clear attributes on `<html>`. Decide from the host name or your build configuration.

### 4. Protect forms that your script submits

A script-submitted form (React, Vue, any `fetch` flow) cannot receive the hidden `nox_request_id` field. Read `form.dataset.noxRequestId` at the top of your submit handler, and call `protect` synchronously when the id is not there yet. The full handler is in [Protected actions](https://noxtica.com/docs/sdk/protected-actions/). The id is withdrawn when your handler returns, so a retry runs a fresh check.

### 5. Install through a tag manager or a CMS theme

A tag manager or a theme has to put the same script element on the page, and nothing more. The collector sees the element, not the tool. Check these points in your tool:

1. **Raw HTML.** Use the tag type that accepts a `<script>` with attributes, or a script that creates the element. The attributes `data-site-key` and `data-auto-init` must be present when the element is added. The loader reads them once.
2. **File name.** Keep `noxtica-collector` in the `src` file name. Do not rename the file.
3. **One tag.** Remove a hand-pasted tag when the tag manager adds one. A second core tag is ignored and logs `NX001`.
4. **Order.** Define the `window.noxtica` stub and any listeners before the core runs. If the tool cannot order them, read `window.noxticaClient` after load.
5. **Trigger.** Fire the tag on every page of the site. For an `api` consent mode, also fire a call to `window.noxticaClient.setConsent(...)` from the trigger that carries your consent decision, after `window.noxticaClient` exists.
6. **Dynamic injection.** A tag added after the page has loaded works. Set every attribute before you append the element, because the loader reads them when it starts.
7. **Google Consent Mode.** When Google tags run on the page, the bridge can follow `analytics_storage`. See [Consent modes](https://noxtica.com/docs/sdk/consent/).

For a CMS theme, add the tag to the template that outputs `<head>`, or to the theme's header-scripts setting. Tag managers and themes differ in how they order and defer scripts; Noxtica does not publish tool-specific steps.

```javascript
// Custom HTML or script-injection example: set the attributes, then append the element.
if (!window.noxtica || !window.noxtica.v) {
	const s = document.createElement('script');
	s.src = 'https://collect.noxtica.com/collector/noxtica-collector-core.js';
	s.async = true;
	s.setAttribute('data-site-key', 'pk_prod_your_site_key_here');
	s.setAttribute('data-auto-init', '');
	s.setAttribute('data-auto-check-once', '');
	document.head.appendChild(s);
}
```

The `window.noxtica.v` check skips the injection when a core script has already claimed the page.

### 6. Check script optimizers and duplicate tags

A script optimizer that rewrites or defers script tags can delay the collector. The Backoffice notes that Cloudflare Rocket Loader defers every script tag it sees unless the tag carries `data-cfasync="false"`. The session-replay early loader requires that attribute; see [Replay recorder head](https://noxtica.com/docs/browser-runtime/#replay-recorder-head). Noxtica publishes no such requirement for the core tag. If an optimizer delays your core tag, test the tag with `data-cfasync="false"`.

A framework that mounts an effect twice, such as React strict mode in development, can add the tag twice. Guard the injection as in step 5. A duplicate is harmless: the second core script logs `NX001` and stops without creating a client.

## Verify it works

1. Reload a page, then navigate to another route without a reload. The route change itself adds no `POST /client/submit` request, unless a Page path protected action matches the new route.
2. `typeof window.noxticaClient` is `'object'`, and `window.noxtica.v` holds the loader version.
3. `document.querySelectorAll('script[src*="noxtica-collector"]').length` is `1`.
4. If a Page path protected action matches a route, navigating to it starts a protected-action check. Calling `await window.noxticaClient.protect('<name>')` resolves a `requestId`, and a bound form receives a `noxtica:protected` event.
5. Your listener received `noxtica:collected` once for the document.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| `NX001: already loaded` in the console | Two core tags: for example a hand-pasted one and a tag-manager one | Remove one. The initial tag keeps running. |
| `window.noxticaClient` is undefined with a tag manager | The injected element lacks `data-auto-init` or `data-site-key`, or the tag manager changed the file name | Set both attributes before appending, and keep `noxtica-collector` in the file name. |
| `403` with `Origin mismatch` on staging | The staging origin uses the production Site Key | Create a domain for the staging origin and use its key. |
| A `noxtica:collected` listener never fires | The listener ran after the event, or the tag was injected late | Register listeners before the tag, or read `window.noxticaResult`. |
| Route changes send a request each time | `checkOnce()` is called per route with `recordVisit` left at `true` | Call it once, or pass `{ recordVisit: false }`. |
| The id is missing in a framework form handler | The handler read it after an `await` | Read `form.dataset.noxRequestId` and call `protect` before any `await`. |
| `window.noxticaClient` appears late | An optimizer defers the script | Test `data-cfasync="false"`, or inject the tag after load on purpose. |
| `@noxtica/sdk` import fails | The package is not on the public registry | Use the script tag, or ask your account team for access. |

## Related

- [Install and Browser Runtime](https://noxtica.com/docs/browser-runtime/): install order, pinned tags and CSP.
- [Script attributes and client options](https://noxtica.com/docs/sdk/script-attributes/): every attribute you can set on the tag.
- [Client API, events and the command queue](https://noxtica.com/docs/sdk/client-api/): the queue stub and events.
- [Protected actions](https://noxtica.com/docs/sdk/protected-actions/): forms, route triggers and the server check.
- [Content Security Policy, hosts and first-party relay](https://noxtica.com/docs/sdk/csp-and-relay/): policies for apps and tag managers.
- [SDK family and availability](https://noxtica.com/docs/sdk/family/): the typed wrapper and its status.
- [Browser SDK troubleshooting](https://noxtica.com/docs/sdk/troubleshooting/): symptoms across the SDK.

---

Source: https://noxtica.com/docs/sdk/csp-and-relay/
Markdown: https://noxtica.com/docs/sdk/csp-and-relay/index.md
Last updated: 2026-10-27

# Content Security Policy, hosts and first-party relay

This page is for the engineer who owns your site's Content Security Policy (CSP) or network allow-list. It lists which hosts the browser collector talks to, which CSP directives it needs, what happens when a directive is missing, and how to put the collector on a subdomain of your own site with a relay hostname.

## What it is

Availability: Evaluation access. Availability depends on your plan, role and the modules enabled for your organisation. Relay hostnames also depend on your plan and on relay provisioning being enabled for your deployment.

The collector uses these hosts:

| Host | What goes there |
| --- | --- |
| `collect.noxtica.com` (your collector host) | The core and extensions scripts, the engine loaders and WebAssembly files, `POST /client/token`, `/client/submit`, `/client/visit` and the interaction tracker. |
| `ingest.noxtica.com` | High-volume telemetry: RUM, RUM error detail, console logs, the client buffer, and the replay policy and upload calls. The loader derives it from the default collector host. |
| `challenges.cloudflare.com` | The Cloudflare Turnstile script, loaded when the server asks the browser for a challenge. |

Both Noxtica hosts must be allowed in `connect-src`. A telemetry call that fails or answers a server error is retried once on the collector host, and the lane then stays on the collector for the rest of the page. A client error (`4xx`) never moves hosts.

A **relay hostname** replaces `collect.noxtica.com` with a subdomain of your own site, for example `noxtica.example.com`. You add a DNS record, Noxtica issues the certificate, and the page then loads the collector from your subdomain. Some privacy tools block third-party hosts; a hostname under your own domain is not third-party. Noxtica does not promise that any blocker lets the collector through.

## Prerequisites

- Control of the CSP header or meta tag of the pages that carry the tag.
- To use a relay hostname:
  - Workspace admin access to Backoffice → Integrations & API → Relay Hostnames, and a step-up MFA confirmation for each change.
  - A plan that includes relay hostnames. Without one, the Backoffice refuses to create the hostname (`plan_feature_required`). Relay hostnames are billed per active hostname; see [Pricing](https://noxtica.com/pricing/).
  - Relay provisioning enabled for your deployment. Otherwise the page says "Relay provisioning is not yet enabled for this deployment".
  - DNS control of the subdomain you want to use.
  - An updated privacy policy and cookie notice. The Backoffice makes you confirm it before it creates the hostname.
- The domain's Site Key and its domain id.

## Steps

### 1. Add the Noxtica sources to your policy

Merge the sources into your own directives. Do not paste a policy over yours: you would drop your own `'self'` entries.

| Directive | Add | Why |
| --- | --- | --- |
| `script-src` | `https://collect.noxtica.com` and `'wasm-unsafe-eval'` | Loads the scripts, and lets the KHAN and Obsidian engines compile WebAssembly. `'wasm-unsafe-eval'` does not allow `eval()`. |
| `worker-src` | `blob:`, next to your own entries | The engines start workers from `blob:` URLs. A worker script must be same-origin, so it cannot come from the collector host. |
| `connect-src` | `https://collect.noxtica.com` and `https://ingest.noxtica.com` | Token and submit calls go to the collector host. Telemetry goes to the ingest host. |
| Turnstile directives | `https://challenges.cloudflare.com` | When your domain uses server-requested challenges, the core loads Turnstile. Allow the host in the directives that Cloudflare's Turnstile documentation names. |

```http
Content-Security-Policy:
  script-src 'self' https://collect.noxtica.com 'wasm-unsafe-eval';
  worker-src 'self' blob:;
  connect-src 'self' https://collect.noxtica.com https://ingest.noxtica.com;
```

Backoffice → Integrations & API → Script & Consent → **CSP & storage** prints the same lines for your hosts. The reasons behind `'unsafe-eval'`, `chrome-extension:` reports, hashes and nonces, and the report-only probe are in [Content Security Policy](https://noxtica.com/docs/browser-runtime/#content-security-policy).

Noxtica does not need `'unsafe-eval'`. Add `'wasm-unsafe-eval'` instead.

If you keep telemetry on the collector with `data-ingest-url` set to the collector origin, `connect-src` needs the collector host alone. If you set `data-ingest-url` to another host, allow that host instead of `ingest.noxtica.com`.

### 2. Know what degrades without `'wasm-unsafe-eval'`

Before it loads any WebAssembly module, the loader checks whether the policy allows WebAssembly. When it does not, the KHAN engine and the GPU attestation engine stop with the message `WebAssembly blocked by Content Security Policy. Add 'wasm-unsafe-eval' to the script-src CSP directive.` Collection carries on with reduced evidence. Native collection and the submit still run. The fix is the directive, not a code change.

Read the engine status in the console. These are diagnostic helpers that support may ask you about:

```javascript
window.NoxticaCollector.getKhanVmStatus();
window.NoxticaCollector.getGpuVmStatus();
```

An enforced violation for the extensions script also shows up in `loadExtensions()` as `reason: 'csp_blocked'`, with `code` set to `script-src-elem` or `script-src`. A `connect-src` that blocks the follow-up diagnostic request reads as `network`.

### 3. Check the policy in report-only mode

Send the policy you want as `Content-Security-Policy-Report-Only` for a day, read the reports, then enforce it. A stricter report-only header next to a permissive enforcing one shows what the permissive policy hides.

```http
Content-Security-Policy-Report-Only: script-src 'self' https://collect.noxtica.com 'wasm-unsafe-eval'; worker-src 'self' blob:; connect-src 'self' https://collect.noxtica.com https://ingest.noxtica.com; report-uri /csp-report
```

### 4. Create a relay hostname (optional)

1. Open Backoffice → Integrations & API → Relay Hostnames. The **DNS setup** box shows the **CNAME target**. It reads "Pending operator configuration" until the target is set for your deployment.
2. Enter the **Domain** (the id of the domain the hostname belongs to) and the **Relay hostname**, for example `noxtica.example.com`.
3. Tick **Acknowledge privacy-notice obligation**: "I confirm I have updated my privacy policy and cookie-consent notice to disclose this relay endpoint, as required by GDPR Art.13/14 and the ePrivacy Directive."
4. Select **Add hostname** and confirm the MFA prompt. The toast says "Relay hostname created. Add the DNS records, then verify."

The hostname must be a public DNS name: letters, digits, hyphens and dots, at least two labels, each label up to 63 characters and the whole name up to 253 characters. A name under `noxtica.com` and a private or reserved name are refused. A tenant can hold a limited number of live hostnames: 3 in the current release. A revoked hostname frees its slot.

### 5. Add the DNS records and verify

1. At your DNS provider, add a CNAME record from your hostname to the **CNAME target**.
2. Add the TXT record that the Backoffice shows under the hostname ("Add this TXT record to verify ownership:"), as `name = value`.
3. Select **Verify** on the hostname row. The status badge moves through **Pending DNS**, **DNS verified** and **Issuing certificate** to **Active**. **Verification failed** means the records did not check out; correct them and select **Verify** again.

Backoffice → Domains → open the domain → **Relay** tab shows the same status read-only.

### 6. Point the page at the relay hostname

When the badge reads **Active**, serve the collector from your hostname:

```html
<script
	src="https://noxtica.example.com/collector/noxtica-collector-core.js"
	data-site-key="pk_prod_your_site_key_here"
	data-api-url="https://noxtica.example.com"
	data-auto-init
	data-auto-check-once
	async
></script>
```

- Keep the file name `noxtica-collector-core.js`. The loader binds a tag by that name.
- `data-api-url` makes the token, submit and visit calls go to your hostname. With `data-ingest-url` left at `auto`, a host other than the default collector keeps its telemetry on itself, so one host serves everything.
- The extensions script is loaded from the folder of the core script, so it comes from your hostname too. The engine files named in the session token follow the host that issued the token.
- Update `script-src` and `connect-src` to your hostname. The Noxtica hosts are no longer needed for this domain unless you set `data-ingest-url` to one of them.
- The Backoffice snippets are generated for the default hosts. Replace the host in the generated tag yourself.
- Keep the Site Key of the domain that the hostname belongs to. The page origin must still match the domain; the relay hostname is the collector host, not your page origin.
- Switch a staging page before production, and run the checks in the next section.

### 7. Revoke a relay hostname

Select **Revoke** on the hostname row and confirm: "Revoke this relay hostname? Telemetry served on it will stop and the certificate will be removed." Switch your tags back to `collect.noxtica.com` before you revoke. Revoke the hostname in the Backoffice, then remove the DNS records.

## Verify it works

1. In DevTools → Network, filter by the collector host. The core script, `POST /client/token`, and after consent the extensions script and `POST /client/submit` come from that host. Telemetry calls go to the ingest host, or to your relay hostname.
2. The console shows no CSP violation that names a Noxtica host.
3. After consent, `window.noxticaClient.getExtensionsState()` is `'attached'`, and `window.NoxticaCollector.getKhanVmStatus()` reports no CSP error.
4. For a relay hostname, `window.noxticaClient.apiUrl` and `window.noxticaClient.ingestUrl` are your hostname.
5. In Backoffice → Domains → the domain → **Relay**, the hostname shows **Active**.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| Console violation for the core or extensions script | `script-src` lacks the collector host or your relay hostname | Add the host. `loadExtensions()` answers `csp_blocked` with `script-src-elem` or `script-src`. |
| `WebAssembly blocked by Content Security Policy` | `script-src` lacks `'wasm-unsafe-eval'` | Add it. Collection continues with reduced evidence until you do. |
| Engine workers fail to start | `worker-src` lacks `blob:`, or it replaced your own entries | Add `blob:` next to `'self'`. |
| Telemetry calls are blocked, token and submit work | `connect-src` lists the collector host but not the ingest host | Allow both hosts, or set `data-ingest-url` to the collector origin. |
| `loadExtensions()` answers `network` while a CSP is in force | `connect-src` blocks the diagnostic request that classifies the failure | Allow the collector host in `connect-src`. |
| A Turnstile widget never appears | `challenges.cloudflare.com` is not allowed | Allow it as Cloudflare documents. |
| Relay: creating the hostname fails with `plan_feature_required` | Your plan has no relay hostnames | Change the plan or contact your account team. |
| Relay: "Relay provisioning is not yet enabled for this deployment" | Provisioning is not set up for your deployment | Contact your account team. |
| Relay: **Add hostname** is disabled | The hostname or domain is empty, the acknowledgement is not ticked, provisioning is unavailable, or the limit is reached | Complete the fields and the acknowledgement, or revoke an unused hostname. |
| Relay: stays on **Pending DNS** | The CNAME or TXT record is missing or wrong | Compare the records with the Backoffice values and select **Verify**. |
| Relay: **Verification failed** | The records did not verify | Correct the records and select **Verify** again. |
| Token call answers `403` with `Origin mismatch` | The page origin is not the one registered for the Site Key. A relay hostname does not change this. | Use the Site Key of the page origin. |

## Related

- [Install and Browser Runtime](https://noxtica.com/docs/browser-runtime/): the CSP section, stable and pinned tags, and the recorder head.
- [Script attributes and client options](https://noxtica.com/docs/sdk/script-attributes/): `data-api-url` and `data-ingest-url`.
- [Cookies, storage and consent categories for your site](https://noxtica.com/docs/compliance/cookies-and-storage/): update your notices before you enable a relay.
- [Domains, site keys and the install card](https://noxtica.com/docs/backoffice/domains/): domain ids and the Relay tab.
- [Browser SDK troubleshooting](https://noxtica.com/docs/sdk/troubleshooting/): symptoms across the SDK.
- [Subprocessors](https://noxtica.com/subprocessors/): who Noxtica uses to deliver the service.

---

Source: https://noxtica.com/docs/sdk/troubleshooting/
Markdown: https://noxtica.com/docs/sdk/troubleshooting/index.md
Last updated: 2026-10-27

# Browser SDK troubleshooting

Use this page when the collector does not start, does not collect, or collects less than you expect. Every symptom below comes from an error body, a result code, an event or a console message that the collector produces. Start with the console checks, then find your symptom in the tables.

## What it is

Availability: Evaluation access. Availability depends on your plan, role and the modules enabled for your organisation.

The core script fails open. A problem in the collector does not block your page, and most failures show up as a missing event, a `reason` and `code` in a result, a `noxtica:error` event, or an HTTP error on a `/client/*` call. This page maps those signals to causes. Concepts are on [Install and Browser Runtime](https://noxtica.com/docs/browser-runtime/); the full reference is on the other pages of this section.

## Prerequisites

- A browser with DevTools (Console and Network).
- The page that shows the problem, served from the origin registered for the Site Key.
- Your Site Key. It is public. Never post a Server API key (`sk_…`), a session token or a cookie value in a ticket.
- For consent questions, the consent mode of the domain: Backoffice → Integrations & API → Script & Consent → **Consent & extensions**.

## Steps

### 1. Read the loader state

Run this in the console of the affected page:

```javascript
({
	version: window.noxtica && window.noxtica.v,                 // loader version, set by the initial core script
	loader: typeof window.NoxticaCollector,                       // 'object' when a core script ran
	client: typeof window.noxticaClient,                          // 'object' when a data-auto-init tag bound
	consent: window.noxticaClient && window.noxticaClient.getConsent(),
	extensions: window.noxticaClient && window.noxticaClient.getExtensionsState(), // 'not-loaded' | 'attached' | 'built-in'
	lastResult: window.noxticaResult,
	lastError: window.noxticaLastError,                           // { source, message, time }
	logLevel: window.NoxticaCollector && window.NoxticaCollector.getLogLevel(),
});
```

To see more, set the log level to `debug` with `data-log-level="debug"` on the tag and reload. The loader is silent by default. See [Script attributes and client options](https://noxtica.com/docs/sdk/script-attributes/).

### 2. Check the Network tab

Filter by your collector host. A working page shows the core script and `POST /client/token` with status `200`. After consent in a gated mode it also shows the extensions script, engine files and `POST /client/submit`. An error body from the collector carries a `requestId`; keep it for support.

### 3. Check consent and the extensions

Read `getConsent()`: `mode`, `modeResolved` and the four categories. Then call `await window.noxticaClient.loadExtensions()` and read `ok`, `reason` and `code`. The tables below explain each value.

### 4. Check the policy

Open the console on a page with the policy in force and look for violations that name a Noxtica host. See [Content Security Policy, hosts and first-party relay](https://noxtica.com/docs/sdk/csp-and-relay/).

### 5. Collect what support needs

Send: your Site Key, the page URL without query strings, the loader version (`window.noxtica.v`), the output of step 1, the failing request with its status and `requestId`, and the time. Contact your account team or use [Contact](https://noxtica.com/contact/). Platform incidents are listed on `status.noxtica.com`.

### 6. Check the browser

The collector needs WebAssembly and `blob:` workers for its engines. GPU attestation also needs WebGPU: without it the loader logs `WebGPU not available` and skips that step. The Web Locks API is optional; a browser without it falls back to a `localStorage` lock for the cross-tab check. A privacy mode, an extension or a network rule that blocks cross-origin requests, storage, workers or WebAssembly reduces the evidence or stops collection, and the page keeps working.

Headless and automated browsers are scored as bots, and your CDN may challenge them. Do not compare risk scores from headless runs. Test on a lab page, as described in [Release checks, testing and versions](https://noxtica.com/docs/browser-runtime/#release-checks-testing-and-versions).

Noxtica does not publish a verified minimum browser version list in this documentation. Test the browsers and privacy modes your own application supports.

## Verify it works

After a fix, reload the page with a clean profile and check:

- `typeof window.noxticaClient` is `'object'` and `window.noxtica.v` holds a version.
- `POST /client/token` answers `200`.
- `window.noxticaLastError` is `undefined`.
- In a gated mode, `getConsent().modeResolved` is `true`; after consent `getExtensionsState()` is `'attached'`.
- Exactly one `noxtica:collected` event fires for the page.

## Troubleshooting

### The script does not start

| Symptom | Cause | Fix |
| --- | --- | --- |
| `window.noxticaClient` undefined and no `noxtica:*` events | The tag lacks `data-auto-init` or `data-site-key`, or the `src` file name has neither `noxtica-collector` nor `/noxtica.js` | Add the attributes and keep the file name. A tag without a Site Key is skipped silently. |
| `window.NoxticaCollector` undefined | The core script did not load: blocked by CSP or a network rule, a `404`, or an integrity failure | Read the failed request in Network and the console. See the CSP page. |
| Pinned tag blocked with an integrity error | The pin is more than three releases old, or the hash was copied from a document | Copy the tag again from Script & Consent → Snippets, or use the stable tag. |
| `NX001: already loaded (v…), duplicate tag v… ignored.` | A second core or combined tag on the page | Remove it. The initial tag keeps running and its version is `window.noxtica.v`. |
| `window.noxtica(...)` does nothing | `window.noxtica` is a plain object without `q`, or the tag lacks `data-auto-init` | Define the stub as a function or array. |
| `NoxticaCollector: siteKey is required` | `createClient` found no Site Key | Pass `siteKey` or keep `data-site-key` on a collector tag. |
| A relay or proxy path loads the script but nothing binds | The proxied file name lost `noxtica-collector` | Keep the file name when you proxy the script. |

### `POST /client/token` fails

| Status and body | Cause | Fix |
| --- | --- | --- |
| `403` `Origin not allowed` | The request had no `Origin` header, so it did not come from a normal browser page | Test from a real page on the registered origin. |
| `403` `Origin mismatch` | The page origin differs from the origin registered for the Site Key | Use the key of the exact origin. Staging needs its own domain and key. |
| `400` `Missing siteKey` | The request body had no Site Key | Check the tag's `data-site-key` or the `siteKey` option. |
| `401` `Invalid siteKey` | The Site Key is unknown or inactive | Copy the key again from Backoffice → Domains. |
| `403` `Tenant suspended` or `Domain disabled` | The account or the domain is not active | Contact your account team. |
| `429` `Rate limit exceeded`, with `Retry-After` | The tenant and client address hit the token rate limit | Wait for `Retry-After`. |
| `429` `quota_exceeded` with code `COLLECTOR_REQUESTS_QUOTA_EXCEEDED` | The monthly collector request quota is used up, when quota enforcement is enabled | Check usage in Backoffice and see [Usage, quotas and metering](https://noxtica.com/docs/billing/usage-and-quotas/). |
| `413` `Payload too large` or `415` `Content-Type must be application/json` | A custom client or proxy changed the request | Do not rewrite collector requests. |

### Consent and gated modes

| Symptom | Cause | Fix |
| --- | --- | --- |
| `noxtica:collected` has `skipped: 'consent_required'` | A gated mode and `deviceId` not granted | Call `setConsent({ deviceId: 'granted' })` after the visitor agrees. Not an error. |
| `getConsent().mode` is `not_required` on an `api` domain | `modeResolved` is `false`: the saved mode has not arrived | Wait for `noxtica:consent-changed`, or declare `data-consent-mode`. |
| `setConsent` throws `NoxticaCollector.setConsent requires granted, denied, or { analytics, replay, deviceId, behavioral }` | A boolean or another shape | Pass `'granted'` or `'denied'`. |
| `setConsent` throws `unknown consent category` or `… must be granted or denied` | A wrong key or value | Use the four category names with the two strings. |
| Extensions load for visitors who declined | Not required mode with automatic loading, or a legacy script URL | See [Consent modes](https://noxtica.com/docs/sdk/consent/). |
| Two `noxtica:collected` events with different ids | Loader older than 3.8.1 | Update to the current loader; take the id from the server verify call. |
| `fingerprintId` in the browser differs from the server | The core and the extensions mint different ids | Use the id from `POST /v1/protected-actions/verify`. |

### Extensions: `loadExtensions()` results

`loadExtensions()` never rejects. It resolves `{ ok: true, loaded }` or `{ ok: false, reason, code, … }`. A later call retries after a failure.

| `reason` | `code` | Cause | Fix |
| --- | --- | --- | --- |
| `consent_missing` | `consent_required` | You passed `{ requireConsent: true }` in a gated mode and no category is granted | Grant a category before you call it, or drop the option. |
| `consent_missing` | `consent_withdrawn` | A queued `loadExtensions` was dropped because the queued consent denies all four categories (loader 3.8.1 and later) | Call `loadExtensions()` after a grant. |
| `csp_blocked` | `script-src-elem` or `script-src` | An enforced CSP blocked the script | Allow the collector host in that directive. |
| `integrity_mismatch` | `sha384_mismatch` | A pinned file's bytes differ from its hash | Copy the pinned tag again. |
| `network` | `http_<status>`, `fetch_failed` | The file returned an HTTP error or no response | Check the host, the proxy and `connect-src`. |
| `timeout` | `script_timeout` | No load or error event within 20 seconds | Retry. Check the network path. |
| `already_loaded` | `script_present` | A `<script>` for the extensions URL is in the page but nothing registered | Remove your own extensions tag, or fix why it did not run. |
| `unknown` | `build_mismatch` | The extensions come from another build than the core | Load core and extensions from the same collector release. |
| `unknown` | `invalid_extensions`, `handoff_failed`, `not_registered` | The extensions did not register or take over | Reload; report with the `error` text. |
| `unknown` | `script_exception`, `script_error` | The browser rejected a file that is reachable, or the script threw | Check the console. |
| `unknown` | `no_pinned_manifest`, `no_document`, `client_destroyed` | The core has no extensions manifest, there is no document, or the client was destroyed | Use a current core, call from a browser page, create a new client. |
| `unknown` | `legacy_loader` | The typed wrapper normalised a boolean from a loader older than 3.8.0 | Update the loader. |

`error` is human text. Do not parse it. The classification is approximate, because the browser's error event carries no cause.

### Protected actions

| Symptom | Cause | Fix |
| --- | --- | --- |
| `protect()` resolves `error: 'undeclared_protected_action'` | The name is not declared for the domain | Declare it and reload. |
| `protect()` rejects with `NoxticaCollector.protect: invalid protected action name` | The name does not match the action grammar | Use lowercase letters, digits, `-` and `_`, starting with a letter. |
| A form posts without `nox_request_id` | The check exceeded the hold time or the script was blocked | Treat it as no client signal. See [Protected actions](https://noxtica.com/docs/sdk/protected-actions/). |
| Verify returns `409`, `404` or `422` | Replay, expired or foreign id, or an action or domain mismatch | See the status table on the protected-actions page. |

### Responses and signatures

| Symptom | Cause | Fix |
| --- | --- | --- |
| Console warnings `Policy signature verification failed` or `Result signature verification failed`, or errors that mention `Missing policySigned envelope` or `Missing resultSigned envelope` | A response without its signed envelope, or whose signature does not verify. A rule or proxy that rewrites collector responses can cause it. | Stop rewriting collector responses. Keep `signatureMode` at `require`. |
| `noxtica:error` with source `Auto-init failed`, `Auto-check-once failed`, `Auto-collect failed` or `Deferred page check failed` | The automatic step threw; `message` holds the cause, cut to 200 characters | Read `window.noxticaLastError.message`, then match it to a row above. |

### Challenges and blocks

| Symptom | Cause | Fix |
| --- | --- | --- |
| `noxtica:challenge` with `status: 'unsupported'` | The browser cannot run the requested method (`gpu-pow` or `turnstile`) | Informational. The server decides what happens next. |
| A full-page overlay or a redirect | The server issued a block for the visit; `noxtica:block` reports `overlay` or `redirect` | Review the risk decision in Backoffice. The page cannot dismiss the overlay. |

## Related

- [Install and Browser Runtime](https://noxtica.com/docs/browser-runtime/): install, consent and the check list.
- [Script attributes and client options](https://noxtica.com/docs/sdk/script-attributes/): every attribute and option.
- [Client API, events and the command queue](https://noxtica.com/docs/sdk/client-api/): events and result shapes.
- [Consent modes, GPC and Google Consent Mode](https://noxtica.com/docs/sdk/consent/): modes and categories.
- [Content Security Policy, hosts and first-party relay](https://noxtica.com/docs/sdk/csp-and-relay/): policy and relay setup.
- [SDK Changelog](https://noxtica.com/docs/changelog/): behaviour that changed between loader releases.

---

Source: https://noxtica.com/docs/sdk/family/
Markdown: https://noxtica.com/docs/sdk/family/index.md
Last updated: 2026-10-27

# SDK family and availability: browser, server and mobile

Noxtica ships one public browser surface, the collector script served from your collector host, and a family of SDKs and tooling around it. This page says what each part is for, which version the source holds on 2026-10-27, and how you get access to the parts that are not public. Use it to decide what to ask for and what to build on plain HTTP.

## What it is

Availability: Evaluation access for the browser collector script (device intelligence). Availability depends on your plan, role and the modules enabled for your organisation. Every package, collection and description file in the table below is distributed privately. For access, ask your account team.

Three statements hold for the whole family:

- The script tag from [Install and Browser Runtime](https://noxtica.com/docs/browser-runtime/) needs no SDK. Everything on the other pages of this section works with the tag alone.
- None of the SDKs is required to call the Server API. Plain HTTP with a Server API key works; see [Server API overview](https://noxtica.com/docs/api/).
- The `@noxtica/sdk` browser wrapper is not installable from the public registry: the registry answered `E404` on 2026-10-27. Treat any copy of a Noxtica package that you find in a public registry as unverified, and do not install it.

## Prerequisites

- A Noxtica account and an account team contact. See [Contact](https://noxtica.com/contact/).
- For a server SDK or plain HTTP: a Server API key (`sk_prod_…`) created in Backoffice, kept on your server. See [Authentication](https://noxtica.com/docs/api/authentication/).
- For the browser: a domain and its Site Key. See [Domains, site keys and the install card](https://noxtica.com/docs/backoffice/domains/).
- For a mobile app: a backend of your own that relays attestation to Noxtica. The mobile SDKs never hold a Server API key.

## Steps

### 1. Choose what you need

| Surface | What it is for |
| --- | --- |
| **Browser collector script** (`noxtica-collector-core.js` and `noxtica-collector-extensions.js`) | Collects the browser signals, handles consent, runs protected actions. A script tag; no package. |
| **`@noxtica/sdk`** (browser wrapper) | A typed wrapper around the script: `init()`, a client, a verdict helper that fails closed on a suppressed verdict, and React, Next.js and Vue helpers. Also helpers to build your own Web KYC capture flow. It never contains the collector; the script always comes from your collector host. |
| **Server SDKs** (Node.js, Python, Go, PHP, Java, .NET, Rust) | Typed clients for the Server API (`/v1/*`), in most languages offline verification of signed result envelopes, and in some languages KYC session helpers and framework middleware. Coverage differs per language; read the README you receive. |
| **Mobile SDKs** (Android, iOS) | App and device attestation clients, KYC capture helpers, and real-user monitoring modules. The device talks to your backend, and your backend relays to Noxtica. |
| **OpenAPI descriptions** | Machine-readable descriptions of the backend API (`v1`, the routes that are not identity verification), the KYC, KYB and KYM API (`kyc`) and the Pulse customer, sign-in and device API (`pulse`). The `v1` description includes `POST /v1/protected-actions/verify`. The public operations of each are published as [`/docs/api/openapi/<api>.json`](https://noxtica.com/docs/api/openapi/v1.json) and `.yaml`, and together as [openapi.json](https://noxtica.com/docs/api/openapi.json); the complete source files come with the deliveries from your account team. |
| **Postman collections** | A hand-written collection for the collector (assets, browser API, backend API, legacy routes) and a generated collection for the backend API, with `local` and `prod` environments that hold placeholders. |

### 2. Read the versions and availability

| Surface | Version in source on 2026-10-27 | Runtime floor | Status |
| --- | --- | --- | --- |
| Browser collector script | Loader 3.8.1 (`window.NoxticaCollector.VERSION`) | A browser with WebAssembly and Web Workers for the engines | Served from your collector host. Documented in this section. |
| `@noxtica/sdk` | 0.3.0 (targets loader 3.8.1, needs 3.8.0 or newer) | A browser; `init()` rejects on a server | Private. Not on the public registry. |
| Node.js SDK | 0.1.1 | Node.js 22 | Private. |
| Python SDK | 0.1.1 | Python 3.10 | Private. |
| Go SDK | 0.1.1, plus an OpenTelemetry module at 0.1.1 | Go 1.25 | Private. Version 0.1.0 is retracted; do not use it. |
| PHP SDK | 0.3.0 | PHP 8.2 | Private. |
| Java SDK | 0.1.1 | Java 17 | Private. |
| .NET SDK | 0.2.2 | .NET 8 | Private. |
| Rust SDK | 0.1.0 | Rust 1.82 | Private. |
| Android SDK | 0.3.2 | Android 7.0 (API level 24) | Private. |
| iOS SDK | 0.2.13 | iOS 15 | Private. |
| OpenAPI descriptions | Each description file carries its own `info.version` | Not applicable | The public operations are published at [openapi.json](https://noxtica.com/docs/api/openapi.json). The complete source files are private. |
| Postman collections | Each collection carries its own version | Not applicable | Private. |

"Private" means the source is not published and the packages are not in a public registry. Access is arranged through your account team. The wrapper's own notes say that its `0.x` versions can carry a breaking typing change in a minor release; read the changelog that comes with any package before you upgrade.

### 3. Ask for access

Ask your account team, or use [Contact](https://noxtica.com/contact/). Say:

1. Which surface and which language or platform.
2. Which environment: evaluation or production.
3. The loader version your pages run, from `window.noxtica.v`, if you ask for the browser wrapper.

Do not copy credentials, package names or build output from another team's repository or from an older example.

### 4. Match the wrapper to the loader

The wrapper and the loader version separately. The script on the page is the loader; the wrapper only types and drives it.

| `@noxtica/sdk` | Loader it needs | Targets | What the pairing changes |
| --- | --- | --- | --- |
| `0.3.x` | 3.8.0 or newer | 3.8.1 | `loadExtensions()` resolves a result object. The consent snapshot gains the optional `modeResolved`. On loader 3.8.0, `modeResolved` is `undefined`: wait while it is `false`, never for `true`. |
| `0.2.x` | any | 3.5.x to 3.7.x | `init()` injects the core script by default. A boolean `loadExtensions()` is normalised to `{ ok, loaded }`. |

Against a loader older than 3.8.0, the wrapper turns the boolean into `{ ok: true, loaded: [] }` or `{ ok: false, reason: 'unknown', code: 'legacy_loader' }`. The full loader history is in [SDK Changelog](https://noxtica.com/docs/changelog/).

### 5. Keep the key types apart

| Key | Where it lives | Used for |
| --- | --- | --- |
| Site Key (`pk_…`) | Public; in the browser tag | Identifies the domain for `/client/*` calls from the registered origin. |
| Server API key (`sk_prod_…`) | Your server only | `/v1/*` calls, including protected-action verification. |

A server key in browser code, a mobile app resource, a URL or a client-visible log is a leak. The mobile SDKs are built so that the device never holds one.

### 6. Verify protected actions over plain HTTP

None of the seven server SDKs has a wrapper for `POST /v1/protected-actions/verify`. Call it with any HTTP client, as shown in [Protected actions](https://noxtica.com/docs/sdk/protected-actions/). The call needs a key with the `read:device` scope. The other Server API calls are in the [API reference](https://noxtica.com/docs/api/reference/).

```bash
curl -X POST "https://collect.noxtica.com/v1/protected-actions/verify" \
  -H "Authorization: Bearer sk_prod_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"requestId":"<uuid from the browser>","action":"login"}'
```

## Verify it works

- **Browser script.** `window.NoxticaCollector.VERSION` and `window.noxtica.v` report the loader version, and `POST /client/token` answers `200`.
- **Wrapper, when you have it.** The loader version meets the minimum in step 4, and `loadExtensions()` resolves an object that has `ok`.
- **Server.** An authenticated request to the Server API returns a result. Handle `401`, `403`, `404` and `429` explicitly. See [Backend Integration](https://noxtica.com/docs/backend-integration/).
- **Protected actions.** The verify call returns `200` for a fresh id and `409` for the same id again.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| The package manager says `@noxtica/sdk` is not found (`E404`) | The wrapper is not on the public registry | Use the script tag, or ask your account team for access. |
| `loadExtensions()` resolves `reason: 'unknown'` with `code: 'legacy_loader'` | The wrapper is newer than the loader on the page | Use a loader of 3.8.0 or newer. |
| `init()` rejects with a browser-only error | It ran on a server | Guard shared code with `isBrowser()`, or load the script tag in the HTML. |
| The wrapper's `setConsent` takes only `'granted'` or `'denied'` | It maps to the legacy analytics form | Use `window.noxticaClient.setConsent({ … })` for categories. |
| `init()` rejects a `pinnedLoader.version` | `pinnedLoader.version` needs `script: 'combined'` | Pin the core with `scriptUrl` and `pinnedLoader.integrity`. |
| A suppressed verdict reads as zero | Code used `verdict.score ?? 0` | Use `isHighRisk(verdict)`, which treats a verdict without a score as high risk. |
| A Go build pulls version 0.1.0 | That version is retracted | Pin version 0.1.1 or newer. |
| There is no server-SDK call for protected-action verification | No facade exists | Use plain HTTP, step 6. |
| A mobile app needs a key | Mobile SDKs relay through your backend | Keep the Server API key on your backend. |

## Related

- [Install and Browser Runtime](https://noxtica.com/docs/browser-runtime/): the script tag.
- [Client API, events and the command queue](https://noxtica.com/docs/sdk/client-api/): what the wrapper drives.
- [Protected actions](https://noxtica.com/docs/sdk/protected-actions/): the verify call over HTTP.
- [Device and app attestation](https://noxtica.com/docs/security/attestation/): the mobile attestation relay.
- [Server API overview](https://noxtica.com/docs/api/), [Authentication](https://noxtica.com/docs/api/authentication/) and [API reference](https://noxtica.com/docs/api/reference/): plain HTTP access.
- [SDK Changelog](https://noxtica.com/docs/changelog/): loader releases and the wrapper pairing table.
- [Developer overview](https://noxtica.com/developers/): the short path through the browser, server, and policy guides.

---

Source: https://noxtica.com/docs/backoffice/domains/
Markdown: https://noxtica.com/docs/backoffice/domains/index.md
Last updated: 2026-10-27

# Domains, site keys and the install card

A domain is a website origin that you register in Backoffice. Each domain gets a site key that the collector script uses to send results for that origin. A workspace Admin registers the domain here, copies the key and then installs the script from Script & Consent.

## What it is

Availability: Availability depends on your plan, role and the modules enabled for your organisation.

- **Domains list** (`Backoffice → Administration → Domains`): one row per registered origin with its tenant (platform operators only), origin, masked site key, status, tracker switch, retention, last seen time and actions.
- **Site key**: a public identifier. It is safe to put in page source because it is bound to the registered origin: the collector accepts submissions from that origin only. Keep one domain, and one key, per environment. A site key is not a secret API key; server keys live under [Integrations and API pages](https://noxtica.com/docs/backoffice/integrations/).
- **Install Noxtica card**: a card under the list. It links to **Integrations & API → Script & Consent → Snippets**, the single place that holds install snippets, consent modes and checks. The card does not duplicate them.
- **Domain detail** (`/domains/<id>`): the full record for one origin, with the tabs **Configuration**, **Risk rules**, **Integration**, **Relay** and **Recent events**.

The full install walkthrough is in [Install & Browser Runtime](https://noxtica.com/docs/browser-runtime/). Consent behaviour is in [Consent modes, GPC and Google Consent Mode](https://noxtica.com/docs/sdk/consent/).

## Prerequisites

- The Admin role in the workspace. Viewers and Analysts do not see the **Domains** page in the sidebar. See [Backoffice guide](https://noxtica.com/docs/backoffice/overview/).
- An authenticator app. Creating, changing, rotating and deleting a domain each ask for a fresh MFA check.
- The exact origin to register: scheme, host and optional port, with no path, query or fragment. Use `https`. Plain `http` is accepted for `localhost` and `127.0.0.1` development only.
- Room in your plan's domain limit. Your plan sets the maximum number of domains.
- Some per-domain controls (proof-of-work attestation, GPU VM rollout, cookie content capture, the Client RUM sample rate) are changed by Noxtica operators on request. They appear read-only to a workspace Admin.

## Steps

### 1. Add a domain

1. Open `Backoffice → Administration → Domains`.
2. Select **Add domain**.
3. Enter the **Origin URL**, for example `https://www.example.com`. Do not include a path, query string or hash.
4. Select **Create domain** and enter your MFA code when asked.

The console checks the format before it sends the request, and the server checks it again:

| Rule | Message |
| --- | --- |
| Must parse as a URL | `Invalid URL format. Expected: https://example.com` |
| No path, query or hash | `Origin should not include path, query, or hash (e.g., https://example.com)` |
| `https` only, except localhost | `HTTP origins are only allowed for localhost development` |
| Each origin once | `Origin already registered` |
| Plan limit | `Maximum domains limit reached for this tenant` |

On success a toast reads: "Domain "<host>" created in API consent mode: the page check stays off until your site calls setConsent()." The new row has the status **Active**.

### 2. Copy the site key

In the **Site key** column the key is masked. Select **Reveal site key** to show it, then **Copy**. The domain detail header has the same **Site key** copy button. Use a separate domain, with its own key, for staging and production.

### 3. Install the script

Select **Install Noxtica → Script & Consent** on the Domains page, or open the domain and use the **Integration** tab. Both open `Integrations & API → Script & Consent` on the **Snippets** tab. The domain tab link preselects the domain (`?tab=snippets&domain_id=<id>`). Copy the core script and add it to every page. The walkthrough is [Install & Browser Runtime](https://noxtica.com/docs/browser-runtime/).

### 4. Know the consent default for new domains

A domain that you create now starts in **API** consent mode. Until your site calls `noxticaClient.setConsent()` (or `noxtica('setConsent', …)`) with the `deviceId` category granted:

- the page check is skipped, and `noxtica:collected` carries `skipped: 'consent_required'`;
- nothing persistent is written on the visitor's device;
- only protected actions run.

Domains that existed before this default keep the mode they have. To change a domain's mode, including **Not required**, open the domain and use `Configuration → Client consent mode` (options **Not required**, **API**, **Cookie**), or use `Script & Consent → Consent & extensions`. A cookie mode takes a cookie name (1 to 64 letters, digits, underscores, dots or hyphens) and an optional value (up to 128 characters from letters, digits and `_ . : % + -`). See [Consent modes, GPC and Google Consent Mode](https://noxtica.com/docs/sdk/consent/).

### 5. Review and change per-domain settings

Open a domain from the list. The **Configuration** tab is a stack of cards:

| Card | What you can change | Bounds and notes |
| --- | --- | --- |
| Canonical origin | Nothing; copy the origin | Submissions are accepted from this origin only. Several origins per domain are not available |
| Lifecycle | **Status** (enable or disable), **Tracker collection** | Disabling stops new submissions; existing data stays. With the tracker off the script is served but does not POST submissions |
| Retention | **Retention (days)**, **Check interval (days)**, **Token refresh interval** | Retention override 1 to 365 days; empty inherits the tenant value. Check interval 1 to 30 days. Token refresh 30 seconds to 24 hours, never below your plan floor. **Effective** shows the value the script receives |
| Client log level | Console verbosity of the script's own diagnostics: Silent, Error, Warn, Info, Debug, or SDK default | A `data-log-level` attribute or an `init` option always overrides it |
| Client consent mode | **Not required**, **API**, **Cookie** | See step 4 |
| Tracker policy | VM telemetry, Debug signals, Browser interactions, Heatmaps, User journeys, App events, Sample rate | Sample rate 0.0 to 1.0. Heatmaps and User journeys need Browser interactions and default to off |
| Hardware Attestation | PoW attestation, GPU VM, rollout percentage | Operator-controlled. Runs real work in the visitor's browser |
| Cookie capture | Cookie content capture | Operator-controlled. Off by default; needs a documented lawful basis |
| Client RUM | Sample rate | Operator-controlled |

The other tabs:

- **Risk rules**: rules added here apply to this origin only. Tenant-wide rules from `Detection & Collection → Rules & Risk Scoring` apply alongside them. See [Detection and collection settings](https://noxtica.com/docs/backoffice/detection-settings/).
- **Integration**: a link to Script & Consent for this domain.
- **Relay**: a read-only list of first-party relay hostnames for this domain, with the CNAME target and TXT record to publish. Provision hostnames in `Integrations & API → Relay Hostnames`. See [Content Security Policy, hosts and first-party relay](https://noxtica.com/docs/sdk/csp-and-relay/).
- **Recent events**: audit entries for this domain, such as updates and rotations. See [Audit log and data export](https://noxtica.com/docs/security/audit-log-and-exports/).

The header of the detail page shows four counters: **Submissions (30d)**, **Blocked**, **Challenged** and **Pass-through rate**. A **Verdict funnel (last 30 days)** card shows how submissions narrow from intake to decisions. Counts under the anonymity threshold are hidden, and a hidden stage is not a zero.

### 6. Disable, rotate or delete

- **Disable**: on the list use the power icon; on the detail page use **Lifecycle → Status**. A disabled domain shows **Revoked** on the list and **Disabled** on the detail page. **Enable** resumes collection with the same site key.
- **Rotate**: **Rotate key** on the detail page, or the rotate icon on the list. The current key stops working immediately, so update every snippet that uses it before you rotate. The change needs MFA.
- **Delete**: the trash icon on the list, or **Delete** on the detail page. Type the host name to confirm. Deletion removes the domain, its site key and the data associated with it. It cannot be undone.

### 7. Export the list

Select **Export CSV** above the table to download the domains you can see.

## Verify it works

- The domain row is **Active**, and its masked site key matches the key in your snippet.
- After the script runs on your site, the **Last seen** column shows a time. `Script & Consent → Check it works` walks through the same check on the page side.
- In API consent mode, open your site and confirm that your consent banner calls `setConsent()`. Until it does, the page check is skipped by design.
- On the domain detail page, **Submissions (30d)** counts rise once traffic is collected.
- After you change a setting or rotate the key, `Recent events` lists that update or rotation.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| **Add domain** is missing | The Domains page needs the Admin role | Ask a workspace Admin |
| `Origin should not include path, query, or hash` | You entered a full page URL | Enter just `https://host` |
| `HTTP origins are only allowed for localhost development` | You used `http` for a real host | Register the `https` origin |
| `Origin already registered` | The origin exists in the workspace, or the same origin is registered elsewhere | Use the existing domain, or ask your account team |
| `Maximum domains limit reached for this tenant` | Your plan's domain limit | Delete an unused domain or ask your account team |
| The script loads but no page check appears | A new domain starts in API consent mode | Call `setConsent()` after consent, or change the mode under Client consent mode |
| Collection stopped after a rotation | Snippets still carry the old key | Copy the new key into every snippet |
| No submissions, tracker off | **Tracker collection** is off for the domain | Turn it on under Lifecycle |
| The PoW attestation, cookie capture or Client RUM controls are greyed out | These controls are operator-only | Ask your account team |
| A change asks for a code again | A sensitive change needs a fresh MFA check | Enter the authenticator code |

## Related

- [Backoffice guide: navigation, roles and shortcuts](https://noxtica.com/docs/backoffice/overview/): roles, palette and shortcuts.
- [Install & Browser Runtime](https://noxtica.com/docs/browser-runtime/): the install walkthrough.
- [Script attributes and client options](https://noxtica.com/docs/sdk/script-attributes/): script tag attributes such as `data-log-level`.
- [Consent modes, GPC and Google Consent Mode](https://noxtica.com/docs/sdk/consent/): consent modes and the API.
- [Protected actions: client trigger and server check](https://noxtica.com/docs/sdk/protected-actions/): what still runs without consent.
- [Detection and collection settings](https://noxtica.com/docs/backoffice/detection-settings/): tenant-wide rules, cost levels and probes.
- [Roles and permissions](https://noxtica.com/docs/security/roles-and-permissions/): who can manage domains.

---

Source: https://noxtica.com/docs/changelog/
Markdown: https://noxtica.com/docs/changelog/index.md
Last updated: 2026-10-24

# SDK Changelog

Release notes for the browser collector SDK, the core and extensions scripts served from your collector host. Each entry says what changed, who is affected and what to do. The newest release is first, and the version number is the one the collector reports: `window.noxtica.v` on a page that runs 3.7.0 or later.

Only one release needs a code change on your side: **3.8.0**, tagged **Breaking** below. Every other release is additive or a fix, so a page that adopts none of the new surface keeps working. Releases before 3.5.2 are not listed. Install steps, consent modes, events and the command queue are described on [Install and Browser Runtime](https://noxtica.com/docs/browser-runtime/).

The stable collector URLs serve the latest build. A hashed build you pinned with Subresource Integrity keeps serving for the last few releases, so to take a release, copy the new pinned tag from Backoffice → Integrations & API → Script & Consent → Snippets. The version number names a release, not the exact bytes: when a fix ships without a version bump, the hashed file name and its integrity value identify the build.

## A client-side fingerprintId is a hint

The core (minimal) and extensions (full) runtimes legitimately mint different ids for one browser. A `fingerprintId` that arrives in `noxtica:collected` or `noxtica:cache-hit` is therefore a hint for your page, not an identity. The only authoritative id is the one returned to your backend by `POST /v1/protected-actions/verify`. Release 3.8.1 fixes a race so that one page load produces one page check and one submit; before it, the race could produce two `noxtica:collected` events with different ids. For the server-side step see [Backend Integration](https://noxtica.com/docs/backend-integration/).

## Compatibility with @noxtica/sdk

`@noxtica/sdk` is the typed wrapper around the collector script. It does not contain the collector: the script always comes from your collector host, so the pair that runs on a page is one collector release (this page) and one wrapper release. The [Developers page](https://noxtica.com/developers/) states what is currently published.

| Collector release | `@noxtica/sdk` | Notes |
| --- | --- | --- |
| 3.8.1 | 0.3.0 (targets this release) | 0.3.0 needs a collector core of 3.8.0 or newer. |
| 3.8.0 | 0.3.0 (minimum supported core) | `loadExtensions()` resolves a result object (Breaking). |
| 3.7.x, 3.6.x, 3.5.2 | 0.2.x | 0.2.x types `loadExtensions()` as a boolean and passes the loader's value through. On a 3.8.0 or newer core it still resolves the object at run time, which is always truthy: use `.ok`, or move to 0.3.0. |

Against a core older than 3.8.0, 0.3.0 turns the boolean into the 3.8.0 result shape: `{ ok: true, loaded: [] }` for `true` and `{ ok: false, reason: 'unknown', code: 'legacy_loader' }` for `false`. The session members (`@noxtica/sdk/session`, from 3.7.0) throw on a core older than 3.7.0, as `track()` does on a build that predates it. The wrapper has its own release notes for typings and framework helpers; this page covers the collector.

## SDK 3.8.1 (2026-10-24)

Fixes and consent-handling changes; nothing is removed or renamed.

**Fixed**

- **One page check is one submit.** With consent delivered at `noxtica:ready`, `loadExtensions()` called at the same point and a token response slower than the extensions script, a page check could run twice: two submits, two runtimes and two `noxtica:collected` events with different `fingerprintId` values. A page-check call that is still waiting for the token now joins the runtime when it attached in the meantime. One page load produces one submit.
  - Who: pages that grant consent and call `loadExtensions()` early, with `data-auto-check-once` or `checkOnce()`; most visible on cold devices where the token round trip is slower than loading the extensions script.
  - Do: nothing. Remove any de-duplication you added around `noxtica:collected`, and take the authoritative id from your server-side verify call.
- **No second skipped event.** Replaying an already-settled, skipped page check no longer dispatches a second `noxtica:collected` with `skipped: 'consent_required'`. Only a real result is announced.
- **One token per page session across the core to extensions hand-off.** On the documented install (the core with auto-loaded extensions) the extensions runtime could mint its own token a few seconds after the core's. A payload the core had collected, sealed under the first token, was then submitted under the second token and the server answered `400 Unable to process request`. The core now hands its token to the runtime, which adopts it when it has more than 30 seconds of life left; later rotations mint normally.
  - Who: pages on the documented install that call `collect()` then `submit()` (or `checkOnce()`) with the extensions loaded, on a domain with KHAN armed or a guarded RUM policy.
  - Do: nothing. No configuration or server change. Re-copy a pinned tag to get the build.

**Changed**

- **The pre-init command queue is coalesced.** When the core replays `window.noxtica.q`, every `setConsent` or `consent` update folds into one update (a later key wins) applied at the position of the first one, so you get one `noxtica:consent-changed`. A queued `loadExtensions` is dropped when the folded state denies all four categories: it answers `noxtica:extensions-failed` with `{ ok: false, reason: 'consent_missing', code: 'consent_withdrawn' }`. Invalid entries and `consent gcm` run unchanged. A later live `noxtica('loadExtensions')` is an explicit call and still loads.
  - Who: pages that queue several consent updates before the core loads, or queue `loadExtensions` ahead of a consent banner.
  - Do: expect one `noxtica:consent-changed` for the whole queue. Prefer deciding consent in a `noxtica:ready` handler over queuing it.
- **The signed consent mode is announced, and `getConsent()` says whether it is known.** `noxtica:consent-changed` now also fires when the mode signed for your domain differs from the page's declaration at token time (for example an untagged page on a domain set to API mode: `not_required` becomes `api`). `getConsent()` and the event `detail` carry `modeResolved`, which is `false` until the token applied the signed mode. Auto-loading extensions (`data-extensions="auto"`) fails closed: before the mode is known it needs an explicit grant, and it never runs when every category is denied. A manual `loadExtensions()` is unchanged.
  - Who: pages that rely on auto-load without declaring a consent mode on the tag, and code that compares `getConsent().mode` with the tag's declaration.
  - Do: declare the mode on the tag (`data-consent-mode`) or grant consent explicitly, and gate your own logic on `modeResolved` rather than on `mode` alone.
- **The device cookie is minimal.** `nox_fp_<siteKey>` now carries only the state schema version, the device id and the time of the last submit, which is what recovery of the device id and its cache lifetime need. The last result (risk score, level, confidence, flags) stays in `localStorage` and IndexedDB. A cache hit recovered from the cookie alone returns `cachedResult: null`.
  - Who: sites that describe cookie contents in a cookie notice, and code that reads `cachedResult` after the cookie was the only surviving storage.
  - Do: update the notice wording, and treat `cachedResult: null` as a prompt to check again.

## SDK 3.8.0 (2026-10-12), Breaking

`loadExtensions()` resolves a result object instead of a boolean. An object is always truthy, so `if (await client.loadExtensions())` and `=== true` no longer test success.

**Changed**

- **`loadExtensions()` never rejects and resolves a result.** This covers `client.loadExtensions(options)`, the static `NoxticaCollector.loadExtensions()` and `noxtica('loadExtensions', options)`. Success is `{ ok: true, loaded: string[] }`, where `loaded` is the extensions script URL the core injected (`[]` on the combined bundle, or when a tag you added yourself attached the runtime); later calls resolve the same shape without a second fetch. Failure is `{ ok: false, reason, code, url?, status?, error? }`: `reason` is a closed set, `code` is the finer machine-readable cause, `url` is the attempted file, `status` the HTTP status when one was seen and `error` human text that you should not parse.
- **The extensions events carry the result.** `noxtica:extensions-loaded` and `noxtica:extensions-failed` now have `detail` of `{ message: 'attached' | 'not-loaded', ...result }`. In 3.6.0 and 3.7.0 the detail was that string; read it from `detail.message`. Only a real load attempt dispatches `noxtica:extensions-failed`.
- **`loadExtensions({ requireConsent: true })`** refuses to fetch in a gated mode (API or cookie) while no category is granted and answers `{ ok: false, reason: 'consent_missing', code: 'consent_required' }`. The plain call needs no consent, as before.

| `reason` | Meaning |
| --- | --- |
| `consent_missing` | Only with `requireConsent: true`, or when a queued call was dropped because every category is denied (3.8.1). Nothing is fetched. |
| `csp_blocked` | An enforced Content-Security-Policy violation blocked the script URL. `code` is the effective directive (`script-src-elem` or `script-src`). |
| `integrity_mismatch` | The browser rejected the pinned file and its hash differs from the pin (`code: sha384_mismatch`). |
| `network` | The file could not be fetched (`code: http_<status>` or `fetch_failed`). |
| `timeout` | No load or error event within 20 seconds (`code: script_timeout`). The next call retries. |
| `already_loaded` | A script tag for the URL is already in the page but nothing registered (`code: script_present`). Nothing is injected. |
| `unknown` | Everything else, for example a build mismatch or a hand-off error. |

The reason is best effort: the browser's error event carries no cause, so a failed script costs one extra diagnostic request for the same file. A Content-Security-Policy whose `connect-src` also blocks that request reads as `network`.

- Who: code that tests the return value, or that reads the `detail` of the extensions events as a string.
- Do: test `result.ok`, log `result.reason` and `result.code` when it is `false`, and read the old string from `detail.message`. With `@noxtica/sdk`, move to 0.3.0 for the matching types.

## SDK 3.7.0 (2026-10-09)

Additive. A page that uses none of it behaves as 3.6.0, except that the first core or combined bundle publishes `window.noxtica.v` (creating the command-queue stub when the page defined none) and `getConsent()` and `noxtica:consent-changed` details carry `privacySignal`.

**Added**

- **Session API.** `setTag` (replaces a key's values), hashed `identify` (the raw id is never stored or sent), `event`, `getMetadata`, `upgrade`, and a byte-capped pre-roll for conditional recording. Queue commands: `set`, `identify`, `event`, `metadata`, `upgrade`.
- **Session lifecycle.** `pause()`, `resume()`, `stop()` and `start()` on the client and as queue commands. All are idempotent.
- **Google Consent Mode v2 bridge.** `data-consent-mode="gcm"`, `createClient({ consentMode: 'gcm' })`, `client.enableGoogleConsentMode()` or `noxtica('consent', 'gcm')` make the collector follow `analytics_storage`.
- **GPC and DNT on the tracker and console lanes.** With the default signed policy (`honor`), a visitor who sends Global Privacy Control or Do Not Track gets neither the tracker nor console-log capture. `getConsent().privacySignal` reports `'gpc'`, `'dnt'` or `null`, as a local flag that is never sent. The `documented_override` policy runs both lanes.
- **Duplicate-tag guard (`NX001`).** The first core or combined bundle on a page claims it and sets `window.noxtica.v`. A second one logs `NX001` and is refused, so no second client is created.

- Who: everyone gets `window.noxtica.v` and `privacySignal`; the rest is opt-in. Pages with two collector tags (a hand-pasted tag plus a tag-manager copy) now see the `NX001` warning and only the first one runs.
- Do: remove the extra tag if you see `NX001`. If your tracker lane must also run for visitors who send GPC or DNT, review the domain policy before you upgrade.

## SDK 3.6.0 (2026-10-08)

Additive. A page that uses none of it behaves as 3.5.2; the visible differences are that `window.noxtica` is installed as a function by auto-init and `noxtica:ready` is dispatched.

**Added**

- **`noxtica:ready`** on `document` (`detail: { client }`), dispatched once per auto-init tag after the queue ran and before the automatic page check starts. A page without `data-auto-init` gets neither the event nor the queue.
- **The `window.noxtica` command queue** (the gtag pattern): define `window.noxtica = window.noxtica || function () { (window.noxtica.q = window.noxtica.q || []).push(arguments); }` before the core loads. The core replays the queue in order against the first client it creates, then makes `window.noxtica(...)` live. Commands: `setConsent`, `loadExtensions`, `protect`, `checkOnce`. Unknown commands log a warning, and failures go to `noxtica:error` instead of throwing.
- **`noxtica:consent-changed`** (`detail` is the `getConsent()` snapshot), dispatched only when a consent category really changes.
- **`noxtica:extensions-loaded` and `noxtica:extensions-failed`**, dispatched by the core (never by the combined or extensions bundles). The detail was the string `'attached'` or `'not-loaded'`; since 3.8.0 it is the result object.
- **Same-page re-collect is evented.** In API or cookie mode, a page check skipped for consent (`noxtica:collected` with `skipped: 'consent_required'`) runs again with its original options when `deviceId` is granted later on the same page, and announces `noxtica:collected` (and `noxtica:cache-hit` when the cache answers it).

- Who: pages that want to react to readiness, consent or extension loading without polling, and consent banners that load after the collector.
- Do: adopt `noxtica:ready` and the queue when convenient.

## SDK 3.5.2 (2026-10-05)

Additive; completes 3.5.1 of the same day.

**Changed**

- **The legacy URLs serve the core.** `/collector/noxtica-collector.js` (3.5.1) and `/collector/noxtica.js` (3.5.2) return the same bytes, content type, CORS headers and cache class as `/collector/noxtica-collector-core.js`. A core evaluated from a legacy URL defaults `extensions` to `'auto'`: the extensions load immediately in consent mode `not_required`, and on the first category grant in API or cookie mode. An explicit `extensions` option or `data-extensions` value still wins (any value other than `auto` opts out), and the core URL itself keeps the manual default.
- **Pinned combined builds keep working.** The combined bundle is still built, and its hashed file keeps serving the combined bytes for existing integrity pins. `asset-manifest.json` adds `servedAs` and `deprecated` entries for the legacy and combined files.

- Who: pages that still load a legacy URL. Before the extensions attach, extension-lane client methods (`track`, tracker and replay setters) run the core's reduced lane and are not replayed after the hand-off; `maskTextFn` and `maskInputFn` apply only once the extensions runtime owns the client.
- Do: nothing is required. Move to the core tag plus extensions when convenient, as described on [Install and Browser Runtime](https://noxtica.com/docs/browser-runtime/).

---

Source: https://noxtica.com/docs/sdk/consent/
Markdown: https://noxtica.com/docs/sdk/consent/index.md
Last updated: 2026-10-27

# Consent modes, GPC and Google Consent Mode

This page walks a privacy owner and a front-end engineer through the consent controls of the browser collector: the mode saved for each domain, the declaration on the script tag, the four consent categories, the treatment of Global Privacy Control (GPC) and Do Not Track (DNT), and the Google Consent Mode v2 bridge. It describes mechanisms. It is not legal advice; you decide which mode fits your notices.

## What it is

Availability: Evaluation access. Availability depends on your plan, role and the modules enabled for your organisation.

The core script runs on every page without consent. It issues the session token, runs the minimal security check and answers server challenges. The extensions script carries device recognition, analytics, session replay and behavioral signals, and each of those lanes needs its own consent **category**: `analytics`, `replay`, `deviceId` or `behavioral`.

A **consent mode**, saved per domain, decides how the categories get their values:

| Mode | Stored as | Behaviour |
| --- | --- | --- |
| Not required | `not_required` | Nothing waits for a visitor decision. A category is blocked when your page sets it to `denied`; every other category runs as configured. |
| API | `api` | Every category starts denied. Your page grants categories with `setConsent`. Default for new domains. |
| Cookie | `cookie:<name>` or `cookie:<name>=<value>` | The collector reads your consent cookie. A match grants all four categories; a missing or non-matching cookie denies them all. |

Domains created before the `api` default keep the mode they have.

When the mode is not `not_required`, the collector also enforces the decision on its own side. The loader adds an `nxc` parameter that lists the granted categories to collector requests, and the collector discards what you have not granted.

## Prerequisites

- Workspace admin access to Backoffice → Integrations & API → Script & Consent. Without that role the settings are read-only. Saving needs a step-up MFA confirmation.
- A consent banner or consent management platform (CMP) whose decision your page can read, for `api` mode, or a cookie from your own domain that it writes, for `cookie` mode.
- The core tag installed as described in [Install and Browser Runtime](https://noxtica.com/docs/browser-runtime/).
- For GPC and DNT policy changes: workspace admin access to Backoffice → Web Analytics & Privacy → Consent & Privacy, and for session replay Capture Policies.
- A decision from your privacy owner on the mode and on the legal basis. See [Legal basis register and receipts](https://noxtica.com/docs/compliance/legal-basis/) and [Cookies, storage and consent categories for your site](https://noxtica.com/docs/compliance/cookies-and-storage/).

## Steps

### 1. Choose the consent mode for the domain

1. Open Backoffice → Integrations & API → Script & Consent.
2. Pick the domain in the **Domain** card.
3. Open the **Consent & extensions** tab.
4. Set **Consent mode** to one of:
   - `Not required — nothing waits for a visitor decision`
   - `API — my page calls setConsent() (default for new domains)`
   - `Cookie — read my consent cookie`
5. For Cookie, fill **Cookie name** and, if needed, **Required value (optional)**. The name takes 1 to 64 letters, digits, `.`, `-` or `_`. The value takes 1 to 128 letters, digits or `. _ : % + -`. Leave the value empty to treat any non-empty cookie as consent. Otherwise the URI-decoded cookie value must contain your text, so a CMP string such as `OptanonConsent` can be matched on one group with `C0002:1`.
6. Select **Save script & consent settings** and confirm the MFA prompt.

The tab also holds the switch **Load the extensions script automatically once consent is granted (immediately in Not required mode)**. In Not required mode it loads the extensions for every visitor, including those who declined your own banner, and the Backoffice shows a warning when you turn it on in that mode.

`gcm` is a client-side declaration, not a saved mode. The Backoffice rejects it.

In cookie mode the loader reads the cookie when it starts and again on `visibilitychange` and `focus`, so a decision made in your banner applies when the visitor returns to the tab. The cookie must be readable by script; an `HttpOnly` cookie is invisible to the loader.

### 2. Declare the mode on the tag (optional)

The saved mode reaches the browser with the session token. Until then, a client without a declaration behaves as `not_required`. If your decision reaches the page by API, declare the mode so the client is strict from its initial line of code:

```html
<script
	src="https://collect.noxtica.com/collector/noxtica-collector-core.js"
	data-site-key="pk_prod_your_site_key_here"
	data-consent-mode="api"
	data-auto-init
	data-auto-check-once
	async
></script>
```

The Snippets tab adds this attribute with the switch **Add data-consent-mode="api" to the core snippet**. The shorthand `data-consent-cookie="<name>"` or `data-consent-cookie="<name>=<value>"` declares a cookie mode. An invalid declaration is ignored.

| Mode saved for the domain | Declaration on the tag | Mode the client uses |
| --- | --- | --- |
| `api` or `cookie:…` | any | The saved mode. A tag can neither relax it nor swap it. |
| `not_required`, or unset | `api` or `cookie:…` | The declared mode, so the client is gated before the token arrives. The collector does not enforce it on the server. |
| `not_required`, or unset | none, invalid or `not_required` | `not_required`. |

A declaration is a client-side measure. A domain that must be enforced on the server needs the mode saved in the Backoffice.

`getConsent()` and the `noxtica:consent-changed` event carry `modeResolved`. It is `false` until the saved mode arrived with the token, and `true` afterwards. Wait while it is `false`. A loader older than 3.8.1 does not send the field, so `undefined` means "keep using `mode`".

### 3. Connect your banner to the four categories

| Category | A grant enables |
| --- | --- |
| `analytics` | Real-user monitoring, console-log capture, the interaction tracker and the durable client buffer. |
| `replay` | Session replay recording and upload. |
| `deviceId` | Persistent device storage and the persistent device-recognition token. The full page fingerprint also waits for it. |
| `behavioral` | Behavioral biometrics, pointer and touch tracks, geolocation, cookie contents, favicon, extension and WebRTC probes. |

A granted category still depends on the features enabled for your domain. Consent never switches on a feature your configuration leaves off. For the legal classification of each feature, see [Install and Browser Runtime](https://noxtica.com/docs/browser-runtime/#legal-classification-not-legal-advice).

Call `setConsent` from your banner. Each value is the string `'granted'` or `'denied'`; omitted keys keep their value:

```javascript
function applyChoices(choices) {
	const state = (allowed) => (allowed ? 'granted' : 'denied');
	window.noxticaClient.setConsent({
		analytics: state(choices.statistics),
		replay: state(choices.statistics),
		deviceId: state(choices.preferences),
		behavioral: state(choices.marketing),
	});
}

// Run when your decision is known and the client exists.
document.addEventListener('noxtica:ready', () => applyChoices(readMyChoices()), { once: true });
```

Then load the extensions, unless **Load the extensions script automatically once consent is granted** or `data-extensions="auto"` does it for you:

```javascript
const result = await window.noxticaClient.loadExtensions();
if (!result.ok) console.warn(result.reason, result.code);
```

Legacy forms keep working: `setConsent('granted' | 'denied')` sets `analytics`, and `setReplayConsent(true | false)` sets `replay`.

What a denial does:

- `deviceId` denied: the persistent device stores are deleted and the device id stays in memory and `sessionStorage`.
- `analytics` denied: the tracker and RUM stop and the buffered analytics events are purged.
- `replay` revoked while recording: the recorder detaches.
- A repeated call with the same values changes nothing and fires no `noxtica:consent-changed`.

In Not required mode a grant is not needed: an explicit `denied` is the sole value that blocks a category. When persistent device recognition is switched off for the domain, a gated mode never writes the persistent device id, even after `deviceId` is granted.

A page check that your banner has not yet allowed is skipped, not failed. `noxtica:collected` then carries `skipped: 'consent_required'`, and the check runs by itself when `deviceId` is granted later on the same page.

### 4. Decide how to treat GPC and DNT

The browser reports the signal in `getConsent().privacySignal`: `'gpc'` when `navigator.globalPrivacyControl` is `true`, `'dnt'` when `navigator.doNotTrack` is `'1'` or `'yes'`, otherwise `null`. The field is a local flag; the loader adds it to no request body. Browsers also send `Sec-GPC` or `DNT` request headers, and the collector reads those.

The domain policy decides what the signal does:

| DNT/GPC policy | A visitor who sends the signal |
| --- | --- |
| `Honor` (default) | The tracker (clicks, scroll dwell, page views and custom events), console-log capture and RUM do not run for that visitor. |
| `Documented override` | Those lanes run. Your tenant has recorded a legal basis that overrides the signal. |

Set the policy in Backoffice → Web Analytics & Privacy → Consent & Privacy. The page lists domains that still need a consent or privacy decision. For each one, set **Legal basis**, **Requires consent** and **DNT/GPC policy**. **Documented override** needs an approved legal basis and the checkbox **Acknowledge documented override**. Saving needs step-up MFA.

Session replay has its own **DNT/GPC policy**, with the same two values, in its replay policy under Backoffice → Web Analytics & Privacy → Capture Policies. See [Session replay](https://noxtica.com/docs/observability/session-replay/).

The collector backs the client up. With policy `Honor` and a request that carries `Sec-GPC: 1` or `DNT: 1`:

- `POST /client/tracker` answers `200` with `{ "ok": true, "eventsProcessed": 0, "reason": "dnt_gpc_honored" }`, and nothing is stored.
- Console-log upload is refused with `console_logs_dnt_gpc_honored`.
- For replay, the replay policy call answers `{ "ok": false, "enabled": false, "reason": "replay_dnt_gpc_honored" }` and no upload capability is issued.

The loader does not read the signal in the core steps: the session token, the minimal security check, the anti-automation counters and protected actions.

### 5. Bridge Google Consent Mode v2 (optional)

Use the bridge when your CMP already drives Google Consent Mode. Turn it on in one of four ways:

```html
<script
	src="https://collect.noxtica.com/collector/noxtica-collector-core.js"
	data-site-key="pk_prod_your_site_key_here"
	data-consent-mode="gcm"
	data-auto-init
	async
></script>
```

```javascript
noxtica('consent', 'gcm'); // command queue; also client.enableGoogleConsentMode() or createClient({ consentMode: 'gcm' })
```

What the bridge does:

- It reads Google's consent state from `window.google_tag_data.ics`, listens for changes to `analytics_storage` and `ad_storage`, and picks up a decision made before the collector loaded. If Google's state is not on the page yet, nothing is granted, and the bridge checks once a second for about five minutes.
- `analytics_storage` maps to the `analytics` category and to nothing else. `replay`, `deviceId` and `behavioral` keep needing your explicit `setConsent`. `ad_storage` is read and ignored.
- It can tighten and cannot loosen. On a domain saved as `api` or `cookie`, Google can deny what your decision allowed, and can never grant what the saved mode withholds. On a domain saved as `not_required`, a tag that declares `gcm` makes the client behave as gated until Google says `granted`.
- `getConsent().mode` reads `gcm` while the bridge is on, and each real change fires one `noxtica:consent-changed`.

Google Consent Mode is a signal format. It is not a legal basis, and mapping it to a single category keeps a Google `analytics_storage` grant from being read as consent to replay or device recognition.

### 6. Test the result

1. Load the page in a clean profile with your banner unanswered. In DevTools → Network you see the core script and `POST /client/token`. `localStorage` holds no `nox_` keys, and `sessionStorage` holds the token.
2. Read the effective mode after the token arrived:

```javascript
document.addEventListener('noxtica:collected', () => {
	const consent = window.noxticaClient.getConsent();
	console.assert(consent.mode === 'api', 'unexpected consent mode', consent);
});
```

3. Answer the banner with consent. Expect `noxtica:consent-changed`, then `noxtica:extensions-loaded`, then a `noxtica:collected` with a `fingerprintId`. Collector requests now carry `nxc=` with one letter per granted category: `a` analytics, `r` replay, `d` deviceId, `b` behavioral.
4. Withdraw a category and confirm the matching storage disappears.

Once the extensions are loaded, the events `noxtica:consent-rejected` and `noxtica:consent-reset` on `window` purge the durable analytics buffer. Dispatch one from your banner when a visitor rejects or resets consent and you want that purge: `window.dispatchEvent(new CustomEvent('noxtica:consent-rejected'))`.

## Verify it works

- `getConsent()` shows the mode you saved and `modeResolved: true`.
- Before consent in a gated mode, the page makes no call to Noxtica other than the core script and `POST /client/token`, and `noxtica:collected` reports `skipped: 'consent_required'`.
- After consent, the extensions load, `nxc` appears on collector requests and `noxtica:collected` carries a `fingerprintId`.
- For a visitor with GPC on and policy `Honor`, `privacySignal` is `'gpc'` and no tracker or RUM request leaves the page.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| `getConsent().mode` is `not_required` right after load on an `api` domain | The saved mode has not arrived. `modeResolved` is `false`. | Wait for `noxtica:consent-changed`, or declare `data-consent-mode="api"` on the tag. |
| The extensions load for visitors who declined your banner | The domain is in Not required mode, with **Load the extensions script automatically once consent is granted** on or a legacy script URL | Switch the domain to API or Cookie, or turn the switch off. |
| `setConsent` does nothing in Not required mode | In that mode `denied` is the sole value with an effect | Use API or Cookie mode when visitors must decide first. |
| `TypeError: NoxticaCollector.setConsent requires granted, denied, or { analytics, replay, deviceId, behavioral }` | You passed `true`, `false` or another shape | Pass the strings `'granted'` or `'denied'`. |
| Cookie mode never grants | The cookie name differs, the value is not contained in the decoded cookie, or the cookie is `HttpOnly` or set on another host | Match the name exactly and use a script-readable first-party cookie. |
| In cookie mode a banner change is seen late | The loader reads the cookie at start and on `visibilitychange` and `focus` | Reload, or switch tabs and return. |
| `noxtica:collected` has `skipped: 'consent_required'` | `deviceId` is not granted in a gated mode | Grant `deviceId` after the visitor agrees. This is not an error. |
| Google bridge grants nothing | Google's consent object is not on the page, or solely `ad_storage` changed | Make the Google consent default and update run on the page. The bridge reads `analytics_storage`. |
| The Backoffice says a setting is not available on the workspace's database version yet | The setting is not enabled for your organisation | Nothing is written. Try again later or contact your account team. |
| Saving asks for MFA | Changing the consent mode is a step-up action | Complete the prompt. |
| The consent controls are read-only | Your role is not workspace admin | Ask a workspace admin. |

## Related

- [Install and Browser Runtime](https://noxtica.com/docs/browser-runtime/): install, storage disclosure and the legal classification table.
- [Client API, events and the command queue](https://noxtica.com/docs/sdk/client-api/): `setConsent`, `getConsent` and the consent events.
- [Script attributes and client options](https://noxtica.com/docs/sdk/script-attributes/): `data-consent-mode`, `data-consent-cookie` and `data-extensions`.
- [Protected actions](https://noxtica.com/docs/sdk/protected-actions/): the minimal security check that runs without consent.
- [Cookies, storage and consent categories for your site](https://noxtica.com/docs/compliance/cookies-and-storage/): what to disclose in your cookie notice.
- [Legal basis register and receipts](https://noxtica.com/docs/compliance/legal-basis/): recording the basis behind a DNT/GPC override.
- [Cookie policy](https://noxtica.com/cookies/): Noxtica's own cookie notice.

---

Source: https://noxtica.com/docs/compliance/cookies-and-storage/
Markdown: https://noxtica.com/docs/compliance/cookies-and-storage/index.md
Last updated: 2026-10-27

# Cookies, storage and consent categories for your site

A privacy or web owner uses this page to disclose what the Noxtica browser SDK writes on a visitor's device. It lists each cookie and storage entry with its store, lifetime, writer and consent category. It also explains how Do Not Track (DNT) and Global Privacy Control (GPC) signals change what the collector accepts.

The tables are an engineering inventory, not legal advice. Your counsel decides how to classify each entry under the rules that apply to you. The cookie notice for Noxtica's own websites is at [Cookies](https://noxtica.com/cookies/).

## What it is

Availability: depends on your plan, role and the modules enabled for your organisation.

`<sk>` below is the Site Key of your domain. The SDK has two scripts. The **core** script runs on every page. The **extensions** script runs after your page allows it. The core writes no cookie, no localStorage and no IndexedDB. It writes per-tab sessionStorage entries and nothing else. Everything persistent comes from the extensions.

### Cookie and storage inventory

| Name | Store | Lifetime | Written by | Consent category |
| --- | --- | --- | --- | --- |
| `nox_fp_<sk>` | Cookie, localStorage, IndexedDB | 400 days | Extensions | `deviceId` |
| `nox_itp_canary_<sk>` | Cookie, localStorage, IndexedDB | 400 days | Extensions | `deviceId` |
| `nox_tri_<sk>` | Cookie, localStorage, IndexedDB | 400 days | Extensions | `deviceId` |
| `nox_kv_<sk>` | IndexedDB database that holds the three keys above | Same as the keys | Extensions | `deviceId` |
| `nox_lock_<sk>` | localStorage | At most 30 seconds | Extensions | `deviceId` |
| `nox_buf_<sk>` | IndexedDB | Undelivered events dropped after 72 hours | Extensions | `analytics` |
| `noxtica.session.<sk>.token` | sessionStorage | Until the tab closes | Core | None, security session state |
| `noxtica.session.<sk>.protect.<action>` | sessionStorage | Until the tab closes, read once and removed | Core | None, security session state |
| `noxtica.session.khanvm`, `noxtica.session.gpuvm` | sessionStorage | Until the tab closes | Extensions | None |
| `__noxtica_khan_accel_v1` | sessionStorage | Until the tab closes | Extensions | None |
| `nx_replay_tab_id`, `nx_replay_session_v1` | sessionStorage | Until the tab closes, or 30 minutes idle by default | Extensions | `replay` |
| `cookietest`, `_nox_test` | Cookie, localStorage, sessionStorage | Removed in the same call | Extensions | None |

What each entry holds:

- `nox_fp_<sk>` is the device record: the device identifier, the last-submit time and the state schema version. The localStorage and IndexedDB copies also keep the last check result (score, risk level, confidence, flags). From SDK 3.8.1 the cookie copy holds only the schema version, the device identifier and the last-submit time, as URI-encoded JSON.
- `nox_itp_canary_<sk>` is a purge canary, a timestamp that tells the SDK a browser purged its storage.
- `nox_tri_<sk>` is a token refresh interval hint.
- `nox_lock_<sk>` is a cross-tab lock. It is used when the browser has no Web Locks API, and it is not written while persistent storage is closed.
- `nox_buf_<sk>` buffers real-user-monitoring and console-log events until they are delivered.
- `noxtica.session.<sk>.token` caches the session token so later pages in the same tab skip a round trip.

### Cookie attributes

The three device cookies `nox_fp_<sk>`, `nox_itp_canary_<sk>` and `nox_tri_<sk>` are written by script with these attributes.

| Attribute | Value |
| --- | --- |
| Lifetime | 400 days |
| Path | `/` |
| Domain | Not set, so the cookie is host-only |
| SameSite | `Lax` |
| Secure | Added on https pages |
| HttpOnly | Not set. A script writes the cookie and the SDK reads it back to restore storage that a browser purged. |

### Consent categories

| Category | What a grant enables | Storage it governs |
| --- | --- | --- |
| `deviceId` | Persistent device storage and the persistent device-recognition token. | The three device keys, `nox_kv_<sk>` and `nox_lock_<sk>`. |
| `analytics` | Real-user monitoring, error detail, console-log capture, the interaction tracker and the durable event buffer. | `nox_buf_<sk>`. |
| `replay` | Session replay recording and upload. | `nx_replay_tab_id`, `nx_replay_session_v1`. |
| `behavioral` | Behavioral signals, pointer and touch tracks, geolocation, cookie contents, the extension probe, favicon detection and the WebRTC probe. | No storage entry. |

In a gated consent mode (`api` or a cookie mode), nothing persistent is written until `deviceId` is granted and the domain's persistent device recognition setting is on. Before that, the three device keys are held in memory and sessionStorage under the same names. When `deviceId` is withdrawn, the SDK deletes the three keys from localStorage and cookies and deletes the IndexedDB database `nox_kv_<sk>`. In the `not_required` mode the extensions write the device record as soon as they load, unless your page denies `deviceId`. See [Consent modes](https://noxtica.com/docs/sdk/consent/).

### Third-party network contacts

| Contact | When it happens |
| --- | --- |
| `challenges.cloudflare.com` | The SDK loads Cloudflare Turnstile when the server requests a challenge. |
| `stun.l.google.com` on port 19302 | The WebRTC probe uses this public STUN server. It runs when the `behavioral` category is allowed and the probe is enabled for your domain. |

### DNT and GPC

The SDK reports a visitor's browser signal in `getConsent().privacySignal`: `gpc` when `navigator.globalPrivacyControl` is true, `dnt` when `doNotTrack` is `1` or `yes`, otherwise `null`. Browsers send `Sec-GPC: 1` or `DNT: 1` on requests.

The collector acts on the signal according to the domain's DNT/GPC policy. Real-user monitoring, error detail, console logs and the interaction tracker follow the policy you set in Web Analytics & Privacy → Consent & Privacy. Session replay has its own DNT/GPC policy per domain in Web Analytics & Privacy → Capture Policies. New domains start on **Honor** in the Consent & Privacy decision, and the Capture Policies form starts on **Honor** too. With **Honor** and a signal present:

| Lane | What the collector does |
| --- | --- |
| Real-user monitoring | Refuses with HTTP 403 and "RUM not enabled for this domain". |
| Error detail | Refuses with HTTP 403 and `rum_error_detail_dnt_gpc_honored`. |
| Console logs | Refuses with HTTP 403 and `console_logs_dnt_gpc_honored`. |
| Session replay | Refuses with HTTP 403 and `replay_dnt_gpc_honored`. |
| Interaction tracker | Answers HTTP 200 with `{"ok":true,"eventsProcessed":0,"reason":"dnt_gpc_honored"}` and processes nothing. |

With **Documented override** the lane is not refused for the signal. For real-user monitoring, an override needs the approved legal basis `rum_observability` and your acknowledgement. This page does not state that a signal stops the core security check.

## Prerequisites

- A domain with the SDK installed. See [Install and browser runtime](https://noxtica.com/docs/browser-runtime/).
- Your consent mode chosen for the domain. See [Consent modes](https://noxtica.com/docs/sdk/consent/).
- The administrator role to read the CSP & storage tab and to save a consent decision.
- Your counsel's classification of each entry for your jurisdiction.

## Steps

### 1. Open the generated storage table

1. Open Backoffice → Integrations & API → Script & Consent.
2. Select your domain if the page asks for one, then the **CSP & storage** tab.
3. Read the table "Cookies and browser storage written by the collector". Backoffice generates it from the SDK source.

### 2. Choose the rows for your setup

1. If you run the core script alone, disclose the sessionStorage rows marked Core.
2. If you load the extensions, add the rows that match the categories you grant.
3. Add `nox_buf_<sk>` when you grant `analytics`, and the replay rows when you grant `replay`.

### 3. Map categories to your consent tool

Connect your consent tool to the four categories with `client.setConsent`. The mapping is your decision. Example:

```javascript
const client = window.noxticaClient;
const state = (allowed) => (allowed ? 'granted' : 'denied');

cmp.onConsentChanged((choices) => {
	client.setConsent({
		deviceId: state(choices.preferences),
		analytics: state(choices.statistics),
		replay: state(choices.statistics),
		behavioral: state(choices.marketing),
	});
});
```

### 4. Publish the disclosure

Copy the inventory into your cookie policy. State for each row the name, store, lifetime and purpose. Name the third-party contacts that apply to your setup.

### 5. Set the DNT and GPC policy

1. Open Web Analytics & Privacy → Consent & Privacy. Domains that still need a decision are listed. A domain whose decision is already recorded does not appear.
2. In the row of a listed domain, choose the **DNT/GPC policy**. Keep **Honor** unless your counsel advises otherwise. Session replay has a separate **DNT/GPC policy** in Web Analytics & Privacy → Capture Policies.
3. Save and complete the step-up check. A documented override also needs the legal basis and the acknowledgement.

### 6. Set your own console preference

Open Backoffice → Settings. In **Privacy & cookies**, switch **Analytics, session replay and device recognition** on or off for your own account. Turning it off stops collection and deletes what was stored on that device.

## Verify it works

With the consent mode `api` and nothing granted, check the page in your browser developer tools.

- Application → Cookies shows no `nox_` cookie.
- `Object.keys(localStorage).filter((k) => k.startsWith('nox_'))` returns an empty array.
- sessionStorage shows `noxtica.session.<sk>.token`.
- After you grant `deviceId` and load the extensions, the three device cookies appear with `Path=/`, `SameSite=Lax` and a 400-day lifetime, and no `Domain` attribute.
- After you withdraw `deviceId`, the three keys and the `nox_kv_<sk>` database disappear.
- With a browser GPC signal on and the policy on Honor, a real-user-monitoring request returns HTTP 403, and a replay upload is refused.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| A `nox_fp_<sk>` entry exists before consent. | The domain mode is `not_required`, or the entry is the sessionStorage copy held before `deviceId` is granted. | Check the mode with `getConsent().mode`. Choose a gated mode if visitors must decide first. |
| No device cookie appears after consent. | The extensions did not load, or persistent device recognition is off for the domain. | Check `noxtica:extensions-loaded` and the domain setting. |
| `nox_buf_<sk>` is missing. | `analytics` is not granted, or no monitoring event was buffered. | Grant `analytics`. |
| Monitoring requests return HTTP 403 for some visitors. | The policy is Honor and the visitor's browser sends a GPC or DNT signal. | This is intended. Choose a documented override when your counsel approves it. |
| A proxy breaks consent enforcement. | The loader adds an `nxc` query parameter to collector requests. A proxy that removes it makes the collector count nothing as granted. | Keep `nxc` in proxies and rewrite rules. |
| The cookie is larger than expected on an older loader. | Before SDK 3.8.1 the cookie also held the last check result. | Update the loader. |

## Related

- [Consent modes, GPC and Google Consent Mode](https://noxtica.com/docs/sdk/consent/): how consent modes and categories work in the SDK.
- [Install and browser runtime](https://noxtica.com/docs/browser-runtime/): install tags, the Content Security Policy and the consent matrix.
- [Legal basis register and receipts](https://noxtica.com/docs/compliance/legal-basis/): the per-domain consent decision.
- [Privacy and compliance controls in Backoffice](https://noxtica.com/docs/compliance/overview/): map of every privacy page.
- [Cookies](https://noxtica.com/cookies/) and [Privacy Policy](https://noxtica.com/privacy/): the public legal documents for Noxtica's own sites.

---

Source: https://noxtica.com/docs/sdk/protected-actions/
Markdown: https://noxtica.com/docs/sdk/protected-actions/index.md
Last updated: 2026-10-27

# Protected actions: client trigger and server check

A protected action is a step an attacker targets, such as login, sign-up, checkout or identity verification. This page shows how to declare one, how the browser starts its check, and how your backend redeems the result. You need this when the domain is in a consent-gated mode and you still want a device check on those steps.

## What it is

Availability: Evaluation access. Availability depends on your plan, role and the modules enabled for your organisation.

When a declared action runs, the core script runs a **minimal** device check even if the visitor has not consented. The check reads device and browser characteristics, stores nothing on the device, and runs no behavioral, WebRTC, geolocation, replay or analytics collection. The submission carries the reason `protected_action:<name>`. Actions you do not declare are not exempt: an ordinary page view never runs the page fingerprint without consent in the `api` and cookie modes.

The browser receives a `requestId`. Your backend redeems that id with `POST /v1/protected-actions/verify` and learns what the collector decided. The id is single-use, and it is valid for 300 seconds. A missing id is "no client signal", not a pass. Whether a legal basis covers this check is your assessment; see [Consent modes](https://noxtica.com/docs/sdk/consent/).

## Prerequisites

- A domain with the core tag and `data-auto-init`. See [Install and Browser Runtime](https://noxtica.com/docs/browser-runtime/).
- Workspace admin access to Backoffice → Integrations & API → Script & Consent. Saving the list needs a step-up MFA confirmation.
- A Server API key (`sk_prod_…`) that carries the `read:device` scope, kept on your server. See [Authentication](https://noxtica.com/docs/api/authentication/).
- A backend route that receives the request id together with the protected request, for example the login post.
- Up to 16 protected actions per domain.

## Steps

### 1. Declare the actions

1. Open Backoffice → Integrations & API → Script & Consent and pick the domain.
2. Open the **Protected actions** tab.
3. Select **Add protected action** for each action. Fill **Name**, **Match by** and **Pattern**.
4. Check the preview **Resulting token configuration**, then select **Save script & consent settings** and confirm the MFA prompt.

| Field | Rule |
| --- | --- |
| **Name** | 1 to 32 characters: lowercase letters, digits, `-` or `_`, starting with a letter. Must differ from every other name in the domain. Suggested: `login`, `signup`, `checkout`, `kyc`, `password_reset`, `payment_method_add`, `withdrawal`. |
| **Match by** → `Page path` | A path glob that starts with `/`, up to 256 characters. `*` matches within one segment, `**` across segments. No spaces, no `?` or `#` (the query string is ignored), no `***`. Example: `/checkout/**`. |
| **Match by** → `Form or button (CSS selector)` | A selector of a form (the check runs on submit) or a button (on click), up to 256 characters, no control characters. Example: `form#login`. |
| **Match by** → `Page event` | The name of a `CustomEvent` your page dispatches on `window`: 1 to 64 letters, digits, `.`, `:`, `-` or `_`. A digit may come first. |

The Backoffice warns, without blocking the save, when a path matches every page (`/**`, `/*`). The check would then run on every page view without consent. Use the path of the step you protect.

A path match runs when the page loads and again on client-side navigation, because the core watches the History API. Changes reach pages with their next session token.

### 2. Start the check from the page

**A form that navigates.** Add the action name to the form. The check starts when the visitor focuses or presses inside the form, so it has usually finished at submit. A run that settled less than 30 seconds earlier is reused.

```html
<form id="login" data-nox-protect="login" method="post" action="/session">
	<!-- fields -->
</form>
```

On a native submit the core holds the submit for up to 6 seconds, adds a hidden field `nox_request_id`, and submits again. `data-nox-protect-timeout="<ms>"` on the form changes the 6 seconds. If the check is slow or fails, the form goes without the id; the visitor is never blocked.

**A button, a route change or code.** Call `protect` and read the id:

```javascript
try {
	const result = await window.noxticaClient.protect('checkout', { timeoutMs: 6000 });
	if (result.success) sendWithOrder(result.requestId);
	else sendWithOrder(null); // timedOut, undeclared_protected_action, client_destroyed: no client signal
} catch (error) {
	sendWithOrder(null); // the check itself failed: no client signal
}
```

`protect` rejects with a `TypeError` when the name is not a valid action name. An explicit call starts a fresh check unless one for the same action is already running. The result is `{ success, requestId, reason: 'protected_action:<name>', … }` on success, and `{ success: false, timedOut: true, reason }` when `timeoutMs` elapsed.

**A form that your script submits** (React, any `fetch` flow). Your handler calls `preventDefault()`, so a hidden field cannot reach the request. A capture-phase listener starts the check before your handler and publishes the result on the form as `form.dataset.noxRequestId`. A bubbling `noxtica:protected` event fires on the form when the check settles. Read the id synchronously at the top of the handler, and call `protect` synchronously to join a check that is still running:

```javascript
async function onSubmit(event) {
	event.preventDefault();
	const form = event.currentTarget;
	// Both lines run before the initial await: the id is withdrawn when this handler returns.
	const ready = form.dataset.noxRequestId;
	const pending = ready ? null : window.noxticaClient.protect('login', { timeoutMs: 6000 });
	const requestId = ready ?? (await pending).requestId; // undefined on timeout or a blocked script
	await fetch('/api/login', {
		method: 'POST',
		headers: { 'Content-Type': 'application/json', 'X-Request-Id': requestId ?? '' },
		body: JSON.stringify(credentials),
	});
}
```

The id is scoped to one attempt because it is single-use on the server. After your handler returns, the id is removed, and a retry runs a fresh check.

**A page event.** Dispatch the event that you declared, then call `protect` for the same name to receive the id:

```javascript
window.dispatchEvent(new CustomEvent('app:signup-submit'));
```

### 3. Send the request id to your backend

Send the id with the protected request: the hidden `nox_request_id` field of a native form, or a header or body field that you choose in a script-submitted flow. The backend, not the browser, redeems it. Never put a Server API key in browser code.

### 4. Redeem the id on your server

```bash
curl -X POST "https://collect.noxtica.com/v1/protected-actions/verify" \
  -H "Authorization: Bearer sk_prod_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"requestId":"<uuid from the browser>","action":"login","expectedDomain":"www.example.com"}'
```

| Body field | Rule |
| --- | --- |
| `requestId` | Required. The UUID that the browser received. |
| `action` | Required. The action name. An id minted for `login` cannot satisfy a `checkout` check. |
| `expectedDomain` | Optional. A hostname, origin or URL of the page that ran the action, up to 269 characters. The check compares hostnames. |

The body is limited to 2048 bytes. A `200` response carries:

```json
{
  "ok": true,
  "requestId": "<uuid>",
  "action": "login",
  "fingerprintId": "<device id>",
  "verdict": "low",
  "score": 12,
  "confidence": 0.9,
  "domain": "www.example.com",
  "issuedAt": "2026-10-27T10:00:00.000Z",
  "expiresAt": "2026-10-27T10:05:00.000Z",
  "consumed": true,
  "consumedAt": "2026-10-27T10:00:02.000Z"
}
```

`verdict` is one of `minimal`, `low`, `medium`, `high` or `critical`. The values above are an illustration of the shape, not a typical result.

| Status | Body | Meaning |
| --- | --- | --- |
| `200` | `ok: true` and the fields above | Redeemed now. The id is spent. |
| `400` | `invalid_body`, `invalid_request_id`, `invalid_action` or `invalid_expected_domain` | The request is malformed. |
| `401` | The standard API-key error | The key is missing or invalid. |
| `403` | The key lacks the `read:device` scope | Use a key with that scope. |
| `404` | `request_not_found` | The id is unknown, older than 300 seconds, or belongs to another tenant. |
| `409` | `already_consumed`, with `consumed: true` and `consumedAt` | A replay inside the window. Refuse. |
| `413` | `payload_too_large` | The body is over 2048 bytes. |
| `422` | `action_mismatch` or `domain_mismatch` | The action or the hostname differs. The id is not spent; fix the call. |
| `429` | `Rate limit exceeded`, with a `Retry-After` header | Slow down. See [Rate limits](https://noxtica.com/docs/api/rate-limits/). |
| `500` | `Internal server error` | Treat it as no client signal. |

Error bodies from this route look like `{ "ok": false, "error": "<code>", "requestId": "<request id>" }`. For the shared error format, see [Errors](https://noxtica.com/docs/api/errors/).

A server example:

```javascript
// Runs on your server. The key never goes to the browser.
async function verifyProtectedAction(requestId, action, expectedDomain) {
	const response = await fetch('https://collect.noxtica.com/v1/protected-actions/verify', {
		method: 'POST',
		headers: { Authorization: `Bearer ${process.env.NOXTICA_SERVER_KEY}`, 'Content-Type': 'application/json' },
		body: JSON.stringify({ requestId, action, expectedDomain }),
		signal: AbortSignal.timeout(3000),
	});
	const body = await response.json().catch(() => ({}));
	return { status: response.status, ...body };
}

const result = await verifyProtectedAction(req.body.nox_request_id, 'login', 'www.example.com');
if (result.status === 200 && result.ok === true) {
	// result.fingerprintId is the authoritative device id for this action.
	// result.verdict and result.score are signals; you decide what to do with them.
} else {
	// 404, 409, 422, 5xx or a missing id: no client signal. Apply your own step-up. Never treat it as a pass.
}
```

Use the `fingerprintId` from this response as the device id for the action. A device id that the browser sends in a header or in an event is a hint. The server SDKs have no wrapper for this call today; use plain HTTP as above (see [SDK family and availability](https://noxtica.com/docs/sdk/family/)). The full contract is in the [API reference](https://noxtica.com/docs/api/reference/).

### 5. Find the runs in Backoffice

Open Backoffice → Fingerprints, open a device, and open its **Events** tab. A protected-action submission shows the badge **Protected action: login**. A run after consent shows **Consented**. Every change to the list is in the audit log.

## Verify it works

1. Open the page with the banner unanswered in a gated mode. In the console run `await window.noxticaClient.protect('login')`. The result has `success: true`, a `requestId` and `reason: 'protected_action:login'`.
2. Send that id to the verify call within 300 seconds. You get `200` with `consumed: true` and a `fingerprintId`.
3. Send the same call again. You get `409` with `already_consumed`.
4. Send the call with another `action`. You get `422` with `action_mismatch`, and the original id still works.
5. In Fingerprints → device → Events, the submission shows **Protected action: login**.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| `protect()` resolves `error: 'undeclared_protected_action'` | The name is not declared for the domain, or the page still holds an older token | Declare it in Script & Consent → Protected actions and reload. |
| `data-nox-protect` does nothing | The domain has no declared action, so the core installs no trigger | Declare the action with the same name. |
| A native form submits without `nox_request_id` | The check took longer than the hold time, or the script was blocked. The form is released by design. | Treat a missing id as no client signal. Raise `data-nox-protect-timeout` if needed. |
| The id is missing inside a script-submitted handler | The handler read it after an `await` | Read `form.dataset.noxRequestId` and call `protect` before any `await`. |
| Every page view runs a check | A catch-all path such as `/**` | Narrow the path to the protected step. |
| `404 request_not_found` | The id is older than 300 seconds, belongs to another tenant, or is not a protected-action id | Redeem it right after the protected request, with a key of the same tenant. |
| `409 already_consumed` | The id was redeemed before, or the form posted twice | Refuse the request and run a fresh check for the next attempt. |
| `422 action_mismatch` or `domain_mismatch` | The `action` or `expectedDomain` differs from the browser run | Send the same action name and the hostname of the page that ran it. |
| `403` from the verify call | The key lacks the `read:device` scope | Use a key with that scope. |
| The Backoffice says the setting is not available on the workspace's database version yet | The setting is not enabled for your organisation. Nothing was written. | Try again later or contact your account team. |

## Related

- [Consent modes, GPC and Google Consent Mode](https://noxtica.com/docs/sdk/consent/): why protected actions exist and how they differ from consent.
- [Client API, events and the command queue](https://noxtica.com/docs/sdk/client-api/): `protect()` and the `noxtica:protected` event.
- [Single-page apps, frameworks and tag managers](https://noxtica.com/docs/sdk/single-page-apps/): route changes and framework forms.
- [Backend Integration](https://noxtica.com/docs/backend-integration/): device lookup from your server.
- [Authentication](https://noxtica.com/docs/api/authentication/): Server API keys and scopes.
- [Errors](https://noxtica.com/docs/api/errors/) and [Rate limits](https://noxtica.com/docs/api/rate-limits/): shared API behaviour.
- [Browser SDK troubleshooting](https://noxtica.com/docs/sdk/troubleshooting/): symptoms across the SDK.

---

Source: https://noxtica.com/docs/backend-integration/
Markdown: https://noxtica.com/docs/backend-integration/index.md
Last updated: 2026-10-27

# Backend Integration

This guide covers the server side of the evaluated path. The [developer overview](https://noxtica.com/developers/) links the browser, server, and policy guides in order. The maintained server sample is below.

## Trust boundary

The browser passes a returned device identifier to your backend. The backend calls the authenticated device lookup with a server-held credential. The browser must never receive the credential, an Authorization header, or a secret environment variable.

The public v1 device route rejects an unauthenticated request. Evaluation access and an appropriately scoped credential are required before the lookup can return a tenant-scoped record.

A protected-action `requestId` is redeemed the same way, from the backend with a server credential; see [Protected actions](https://noxtica.com/docs/browser-runtime/#protected-actions).

## Handle transport before risk

Your server must preserve these outcomes:

- **Received:** a response contains the fields your evaluated policy requires.
- **Missing:** no record is present for that identifier in the current tenant and retention window.
- **Invalid:** a response exists but lacks fields required by your policy.
- **Rate limited:** the service rejected request frequency; follow the supplied operational guidance.
- **Unavailable:** authentication, authorization, network, or service failure prevented a usable read.

Only a complete received record belongs in a numeric comparison. Missing, invalid, rate-limited, and unavailable states are not score zero and are not low risk.

## Maintained server sample

Send the device identifier to your backend, then call the authenticated v1 route with a server-held key. Replace every synthetic value with credentials and identifiers issued for your evaluation. An automated test checks these samples against fixtures kept with the documentation.

### Read the device on your server

```javascript
export async function lookupDevice({ deviceId, apiKey, fetchImpl = fetch }) {
  const response = await fetchImpl(
    `https://collect.noxtica.com/v1/device/${encodeURIComponent(deviceId)}`,
    { headers: { Authorization: `Bearer ${apiKey}` } },
  );

  if (response.status === 404) return { state: 'missing' };
  if (response.status === 429) return { state: 'rate_limited' };
  if (!response.ok) return { state: 'unavailable' };

  return { state: 'received', record: await response.json() };
}
```

### Keep result states separate

The function below applies the rule above. A record counts as complete when it carries a numeric `score` and `confidence`; every other outcome keeps its own state.

```javascript
export function classifyLookup(result) {
  if (!result || result.state === 'unavailable') return { state: 'unavailable' };
  if (result.state === 'rate_limited') return { state: 'rate_limited' };
  if (result.state === 'missing') return { state: 'missing' };

  const record = result.record;
  if (!record || typeof record.score !== 'number' || typeof record.confidence !== 'number') {
    return { state: 'invalid' };
  }

  return {
    state: 'received',
    score: record.score,
    riskLevel: record.riskLevel,
    confidence: record.confidence,
  };
}
```

## Customer policy

Combine the lookup with the protected operation and the account, authentication, transaction, and abuse context your application already owns. Begin in observation mode. Compare the proposed action with confirmed outcomes before adding step-up or deny behavior.

Set an application deadline and choose a fallback for each protected surface. A successful API response does not prove that one threshold is appropriate for every route.

## Verification checklist

- The credential remains in the server secret store.
- Browser requests carry only the lookup identifier and customer-owned business input.
- Received, missing, invalid, rate-limited, and unavailable paths are exercised.
- Logs omit credentials and unnecessary identifiers.
- Policy changes have an owner, observation evidence, and rollback path.

Run the [maintained server sample](https://noxtica.com/docs/backend-integration/#maintained-server-sample) and then trace the complete [Integration Flow](https://noxtica.com/docs/integration-flow/).

---

Source: https://noxtica.com/docs/api/authentication/
Markdown: https://noxtica.com/docs/api/authentication/index.md
Last updated: 2026-10-27

# API authentication

Server API requests carry a credential in the `Authorization` header. Keep the credential on your server, load it from a secret store or an environment variable, and never put it in client-side code, a URL or a log line.

```http
Authorization: Bearer YOUR_API_KEY
```

## Keys and base URLs

Create and manage server API keys in the Backoffice under Integrations & API. The secret is shown once when a key is created or rotated, so store it immediately. Send each request to the base URL of the API you call:

| Environment | Base URL | Key prefix | APIs |
| --- | --- | --- | --- |
| Production | `https://collect.noxtica.com` | `sk_prod_` | [Identity verification API](https://noxtica.com/docs/api/reference/kyc/), [Risk scoring and agent trust API](https://noxtica.com/docs/api/reference/score/), [Protected actions API](https://noxtica.com/docs/api/reference/protected-actions/), [Device intelligence API](https://noxtica.com/docs/api/reference/device/), [Mobile and device identity API](https://noxtica.com/docs/api/reference/mobile/), [Telemetry ingestion API](https://noxtica.com/docs/api/reference/ingest/), [Observability query API](https://noxtica.com/docs/api/reference/observability/), [Health and public key endpoints](https://noxtica.com/docs/api/reference/status/) |
| Production ingest host | `https://ingest.noxtica.com` |  | [Telemetry ingestion API](https://noxtica.com/docs/api/reference/ingest/), [Observability query API](https://noxtica.com/docs/api/reference/observability/) |
| Production | `https://backoffice.noxtica.com` |  | [MCP server](https://noxtica.com/docs/api/reference/mcp/) |
| Production (not yet deployed) | `https://pulse.noxtica.com` |  | [Pulse tenant API](https://noxtica.com/docs/api/reference/pulse/) |

## Credentials

### ApiKeyAuth

Format: `Authorization: Bearer sk_<random>`.

Server-to-server tenant API key. Header: `Authorization: Bearer sk_...`. Scopes are self-mintable per tenant; the scope required by each operation is listed in that operation's `security` block. Recognized KYC/KYB/KYM scopes: `write:identity` (verify, batch, reverify, evidence, sessions, erasure and activate — all share this one scope, there is no separate `read:identity`), `write:kym` (KYM transactions).

Used by: [Identity verification API](https://noxtica.com/docs/api/reference/kyc/), [Risk scoring and agent trust API](https://noxtica.com/docs/api/reference/score/), [Protected actions API](https://noxtica.com/docs/api/reference/protected-actions/), [Device intelligence API](https://noxtica.com/docs/api/reference/device/), [Mobile and device identity API](https://noxtica.com/docs/api/reference/mobile/), [Observability query API](https://noxtica.com/docs/api/reference/observability/).

### SessionTokenAuth

Format: `Authorization: Bearer kycs.<tenant>.<secret>`.

Opaque hosted-session bearer token, minted once by the matching `POST .../sessions` S2S call and never re-issued. The tenant id rides inside the token itself. Additionally origin-enforced against the tenant's `ALLOWED_ORIGINS` allowlist — a missing or disallowed `Origin` header refuses with `403 origin_not_allowed` even given a valid token.

Used by: [Identity verification API](https://noxtica.com/docs/api/reference/kyc/).

### ApmIngestKeyAuth

Format: `Authorization: Bearer sk_apm_<random>`.

Dedicated ingestion key (`sk_apm_...`, matching `^sk_apm_[A-Za-z0-9_-]{24,256}$`), created per project and environment under Integrations & API → Ingestion API keys. It carries an allowlist of signals chosen at creation and is the ONLY credential the ingestion operations accept: a server API key (`sk_...`), however broad its scopes, is rejected there, and an `sk_apm_` key is rejected on every other route.

Used by: [Telemetry ingestion API](https://noxtica.com/docs/api/reference/ingest/).

### CodingAgentKeyAuth

Format: `Authorization: Bearer cak_<random>`.

Coding-agent read key (`Authorization: Bearer cak_...`, matching `^cak_[A-Za-z0-9_-]{24,256}$`), created under Integrations & API → Coding agent keys with a chosen set of scopes. It is accepted only by the coding-agent read operations, on the ingestion hosts; a server API key (`sk_...`) or an ingestion key (`sk_apm_...`) is rejected there.

Used by: [Observability query API](https://noxtica.com/docs/api/reference/observability/).

### McpTokenAuth

Format: `Authorization: Bearer mcp_<random>`.

MCP token (`Authorization: Bearer mcp_...`) created under Integrations & API, MCP tokens. A static opaque bearer token, not OAuth. It is accepted only by this endpoint.

Used by: [MCP server](https://noxtica.com/docs/api/reference/mcp/).

### tenantKey

Format: `Authorization: Bearer sk_prod_<32 hex>`.

The platform's tenant API key (minted in the Backoffice; scopes `read:pulse`, `write:pulse`), for the tenant's own back-end on `/pulse/v1/tenant/*` only. Looked up through an HMAC hash; a device token or a web session is refused.

Used by: [Pulse tenant API](https://noxtica.com/docs/api/reference/pulse/).

## Scopes

Choose the narrowest scopes that cover what a key has to do. A key without the scope an operation requires is rejected.

| Scope | Credential | Grants | Operations |
| --- | --- | --- | --- |
| `erase:behavioral` | `ApiKeyAuth` |  | [`v1EraseBehavioralSubject`](https://noxtica.com/docs/api/reference/device/#v1EraseBehavioralSubject) |
| `read:apm` | `ApiKeyAuth` |  | [`v1ApmListProjects`](https://noxtica.com/docs/api/reference/observability/#v1ApmListProjects), [`v1ApmListProjectEnvironments`](https://noxtica.com/docs/api/reference/observability/#v1ApmListProjectEnvironments), [`v1ApmGetEnvironmentPolicy`](https://noxtica.com/docs/api/reference/observability/#v1ApmGetEnvironmentPolicy), [`v1ApmSearchTraces`](https://noxtica.com/docs/api/reference/observability/#v1ApmSearchTraces), [`v1ApmGetTrace`](https://noxtica.com/docs/api/reference/observability/#v1ApmGetTrace), [`v1ApmListServices`](https://noxtica.com/docs/api/reference/observability/#v1ApmListServices), and 2 more |
| `read:behavioral` | `ApiKeyAuth` |  | [`v1GetBehavioralSubject`](https://noxtica.com/docs/api/reference/device/#v1GetBehavioralSubject), [`v1GetBehavioralSubjectTimeline`](https://noxtica.com/docs/api/reference/device/#v1GetBehavioralSubjectTimeline) |
| `read:device` | `ApiKeyAuth` |  | [`getAgentPassport`](https://noxtica.com/docs/api/reference/score/#getAgentPassport), [`postAgentPassport`](https://noxtica.com/docs/api/reference/score/#postAgentPassport), [`postAgentVerify`](https://noxtica.com/docs/api/reference/score/#postAgentVerify), [`postIpReputation`](https://noxtica.com/docs/api/reference/score/#postIpReputation), [`postScore`](https://noxtica.com/docs/api/reference/score/#postScore), [`postProtectedActionsVerify`](https://noxtica.com/docs/api/reference/protected-actions/#postProtectedActionsVerify), and 8 more |
| `read:events` | `ApiKeyAuth` |  | [`v1ListEvents`](https://noxtica.com/docs/api/reference/device/#v1ListEvents) |
| `read:export` | `ApiKeyAuth` |  | [`v1ExportFingerprints`](https://noxtica.com/docs/api/reference/device/#v1ExportFingerprints), [`v1ExportEvents`](https://noxtica.com/docs/api/reference/device/#v1ExportEvents), [`v1ExportVisits`](https://noxtica.com/docs/api/reference/device/#v1ExportVisits), [`v1ExportScoredEvents`](https://noxtica.com/docs/api/reference/device/#v1ExportScoredEvents), [`v1GetEmergingThreats`](https://noxtica.com/docs/api/reference/device/#v1GetEmergingThreats), [`v1ApmGetExport`](https://noxtica.com/docs/api/reference/observability/#v1ApmGetExport), and 1 more |
| `read:fingerprints` | `ApiKeyAuth` |  | [`v1ListDevices`](https://noxtica.com/docs/api/reference/device/#v1ListDevices), [`v1ListAccountDevices`](https://noxtica.com/docs/api/reference/device/#v1ListAccountDevices) |
| `read:privacy_request` | `ApiKeyAuth` |  | [`v1ApmGetPrivacyExport`](https://noxtica.com/docs/api/reference/observability/#v1ApmGetPrivacyExport), [`v1ApmGetPrivacyErasure`](https://noxtica.com/docs/api/reference/observability/#v1ApmGetPrivacyErasure) |
| `read:pulse` | `tenantKey` | Read subject status and links. | [`pulseTenantSubjectStatus`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantSubjectStatus), [`pulseTenantListDecisions`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantListDecisions), [`pulseTenantGetDecision`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantGetDecision), [`pulseTenantGetLink`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantGetLink) |
| `read:reputation` | `ApiKeyAuth` |  | [`v1VerifyReputation`](https://noxtica.com/docs/api/reference/score/#v1VerifyReputation) |
| `read:sealed_results` | `ApiKeyAuth` |  | [`v1GetSealedResultsKey`](https://noxtica.com/docs/api/reference/device/#v1GetSealedResultsKey) |
| `read:visits` | `ApiKeyAuth` |  | [`v1ListVisits`](https://noxtica.com/docs/api/reference/device/#v1ListVisits) |
| `write:apm` | `ApiKeyAuth` |  | [`v1ApmUpdateEnvironmentPolicy`](https://noxtica.com/docs/api/reference/observability/#v1ApmUpdateEnvironmentPolicy), [`v1ApmCreateExport`](https://noxtica.com/docs/api/reference/observability/#v1ApmCreateExport) |
| `write:crawl_voucher` | `ApiKeyAuth` |  | [`v1MintCrawlVoucher`](https://noxtica.com/docs/api/reference/score/#v1MintCrawlVoucher) |
| `write:generate` | `ApiKeyAuth` |  | [`v1GenerateFingerprintBatch`](https://noxtica.com/docs/api/reference/device/#v1GenerateFingerprintBatch), [`v1GenerateSingleFingerprint`](https://noxtica.com/docs/api/reference/device/#v1GenerateSingleFingerprint) |
| `write:handoff` | `ApiKeyAuth` |  | [`postHandoffMint`](https://noxtica.com/docs/api/reference/mobile/#postHandoffMint), [`postHandoffConsume`](https://noxtica.com/docs/api/reference/mobile/#postHandoffConsume) |
| `write:identity` | `ApiKeyAuth` |  | [`kycVerify`](https://noxtica.com/docs/api/reference/kyc/#kycVerify), [`kycAddressDocumentCrossMatch`](https://noxtica.com/docs/api/reference/kyc/#kycAddressDocumentCrossMatch), [`kycVerifyBatchSubmit`](https://noxtica.com/docs/api/reference/kyc/#kycVerifyBatchSubmit), [`kycVerifyBatchStatus`](https://noxtica.com/docs/api/reference/kyc/#kycVerifyBatchStatus), [`kycVerifyBatchResults`](https://noxtica.com/docs/api/reference/kyc/#kycVerifyBatchResults), [`kycVerifyBatchCancel`](https://noxtica.com/docs/api/reference/kyc/#kycVerifyBatchCancel), and 19 more |
| `write:identity:trusted-subject` | `ApiKeyAuth` |  | [`walletSuspend`](https://noxtica.com/docs/api/reference/mobile/#walletSuspend) |
| `write:kym` | `ApiKeyAuth` |  | [`kymTransactionsReport`](https://noxtica.com/docs/api/reference/kyc/#kymTransactionsReport) |
| `write:labels` | `ApiKeyAuth` |  | [`v1WriteLabel`](https://noxtica.com/docs/api/reference/device/#v1WriteLabel) |
| `write:passkey` | `ApiKeyAuth` |  | [`postPasskeyChallenge`](https://noxtica.com/docs/api/reference/mobile/#postPasskeyChallenge), [`postPasskeyRegister`](https://noxtica.com/docs/api/reference/mobile/#postPasskeyRegister), [`postPasskeyAssert`](https://noxtica.com/docs/api/reference/mobile/#postPasskeyAssert) |
| `write:pulse` | `tenantKey` | Issue link codes, unlink and reverse decisions. | [`pulseTenantReverseDecision`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantReverseDecision), [`pulseTenantCreateLinkCode`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantCreateLinkCode), [`pulseTenantUnlink`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantUnlink) |

## Failed authentication

A missing, malformed or revoked credential, and a credential without the required scope, are rejected before the operation runs. See [Errors](https://noxtica.com/docs/api/errors/) for the status codes and bodies.

_This page is generated from the Noxtica OpenAPI specification release `v0.4.0`: `kyc.yaml` version `1.2.0-2026-10-27` (SHA-256 `c91a695cfde0`), `mcp.yaml` version `0.1.0-2026-10-27` (SHA-256 `1a4875efa736`), `pulse.yaml` version `0.9.0-2026-10-27` (SHA-256 `95196a58bb5b`), `v1.yaml` version `1.3.0-2026-10-27` (SHA-256 `3fd15257a022`). Do not edit it by hand._

---

Source: https://noxtica.com/docs/identity-verification-integration/
Markdown: https://noxtica.com/docs/identity-verification-integration/index.md
Last updated: 2026-10-27

# Identity verification integration

This guide takes a backend engineer from a provisioned account to a working hosted identity verification flow. Your server creates a session, your customer completes the steps on a page hosted by Noxtica, and your server reads the outcome by a status read or a signed event. Your server never receives the customer's answers or capture directly.

Results are automated signals. You decide what each outcome means for your customer; Noxtica hands you the evidence and an audit trail.

## Availability

Identity verification has **Controlled availability**. A tenant needs the module provisioned by the account team, and the account team confirms what applies to your tenant. Steps described here as optional apply only when they are enabled for your organisation. See the [product page](https://noxtica.com/products/identity-verification/) for the product overview and the limits of the result.

## Choose how to integrate

Three routes lead to a verification. Pick by who builds the capture experience and who sends the link.

| Route | Who creates the link | Who builds the capture experience | Guide |
| --- | --- | --- | --- |
| Hosted session from your server | Your server, by API | Noxtica hosts the page; you send the customer to it | This page |
| Invitation from Backoffice | A person in your organisation, in Backoffice | Noxtica hosts the page | [Invitations and hosted verification settings](https://noxtica.com/docs/identity-verification-invitations/) |
| Direct API from your server | Not applicable | Your own application | [Self-hosted identity verification (direct API)](https://noxtica.com/docs/identity-verification-self-hosted/) |

All three need the module provisioned for your tenant and, where an API is involved, a server key with the identity permission. Hosted sessions and invitations also need a recorded legal basis and share the settings described in [Invitations and hosted verification settings](https://noxtica.com/docs/identity-verification-invitations/).

## How the flow works

1. Your server creates a session with your own opaque customer reference. The response carries a `sessionId` and a single-use link. Store the `sessionId` next to your customer record.
2. You send the customer to the link: a full-page redirect, a new tab, an email or message, or a QR code.
3. The customer completes the steps on the hosted page in their own browser.
4. Noxtica processes the submission. A finished capture currently waits in the review queue in your Backoffice (`review_pending`) until someone in your organisation records a decision.
5. Your server learns the outcome by reading the session status, or from a signed `kyc.session.completed` event. Read the status before you act on an event.
6. If you set a return link, the customer can go back to your site from the hosted page after a completed outcome. The return link is a convenience, not proof that verification succeeded.

## Before you start

Complete these once per environment:

- **Module provisioned.** Your account team provisions identity verification for your tenant. Until then every request below receives a plain `404`.
- **Hosted verification page configured.** In the Backoffice, open Identity Verification → KYC Invitations → Settings and fill in the business name, privacy notice link and purpose text the customer sees. The KYC pages show a readiness checklist that names anything still missing. Until the page is configured the customer sees a "Verification isn't ready yet" message.
- **Legal basis recorded by your organisation.** An authorised person in your organisation records the legal basis for hosted identity verification in the same Settings page. Noxtica does not choose one for you. Until it is recorded, session creation is refused.
- **A server key with the identity permission.** In the Backoffice, open API & SDK → Server API Keys and create a key with the "Verify identity documents (KYC)" permission ticked. A new key defaults to a narrower permission that cannot create sessions. The secret is shown once, so save it in your server secret store. Server keys start with `sk_prod_`.
- **Approved return hosts (optional).** If you want a return link, add the host names of your return pages under "Approved return destinations" in the same Settings page. Saving that page asks for fresh step-up verification.
- **An events endpoint (optional).** If you do not want to poll, register an HTTPS endpoint under Integrations → Webhooks, subscribe it to the identity events you need, and save the signing secret when it is shown. The secret is shown once.

### Keys and base address

A key's prefix tells you what it is: server keys start with `sk_prod_`. Call `https://collect.noxtica.com` with it. A key that is missing, malformed, unknown or revoked is refused with `401 invalid_api_key`.

- Keep each key in its own secret store entry.
- A signing secret belongs to one endpoint.
- The Identity Verification → KYC Verifications → Integration tab shows ready-to-copy samples.

## Create a session

Send the request from your server. Never place the server key in a browser or a mobile app.

```http
POST https://collect.noxtica.com/v1/kyc/sessions
Authorization: Bearer sk_prod_your_server_key
Content-Type: application/json
Idempotency-Key: your-retry-key
```

### Request fields

The body is a JSON object. Field names are exact: an unknown field is ignored without an error, so a misspelt name silently falls back to its default.

| Field              | Type    | Required | Notes                                                                                                                                                                                          |
| ------------------ | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `subjectRef`       | string  | Yes      | Your own opaque reference for the customer, 1 to 256 characters. Use an identifier from your system, not a name or an email address. Status reads return it to you; events never carry it.     |
| `expiresInSeconds` | integer | No       | How long an unopened link stays valid: 300 to 604800, default 86400. A value outside the range is rejected with a `400`, not adjusted.                                                         |
| `returnUrl`        | string  | No       | An `https` address whose host exactly matches an approved return host, up to 2048 characters. Any other host is rejected with `return_url_not_allowed`.                                        |
| `purpose`          | string  | No       | Short text shown to the customer on the hosted page, up to 500 characters. When you omit it the default purpose from your hosted page settings is used.                                         |
| `idType`           | string  | No       | An optional hint for the document type. Leave it out unless your account team asks you to send it; the customer chooses on the page.                                                           |
| `hostedOptions`    | object  | No       | Per-session switches for optional steps. Leave it out to use your defaults. If you send it, send the complete object your account team supplies; a partial object is rejected with a `400`. |

The request has no field for language, webhook address, or customer contact details. The hosted page follows the customer's browser language, and you register webhook endpoints in the Backoffice.

### Response

A new session returns `200` with this shape:

```json
{
  "ok": true,
  "sessionId": "<uuid>",
  "url": "https://verify.noxtica.com/s/<token>",
  "expiresAt": 1790848845000,
  "requestId": "<request-id>"
}
```

- `sessionId` is a UUID. Store it with your customer record.
- `url` is the single-use link. It is returned once, in this response, and no later call returns it again. Treat it as a secret: do not log it and do not put it in an analytics address.
- `expiresAt` is a time in epoch **milliseconds**, not seconds.
- `requestId` identifies the request. Quote it when you contact support.

### Idempotency

`Idempotency-Key` is optional and must be 8 to 128 characters when present. Without it, every call creates a new session. With it, a retry that carries the same key returns the same `sessionId` with `"replayed": true` and **no** `url`. The key alone identifies the session: a different body under the same key returns the original session.

If a request times out and you never saw the link, you cannot recover it. Create a new session with a new key and let the old one expire.

### Examples

```bash
curl -sS https://collect.noxtica.com/v1/kyc/sessions \
  -H "Authorization: Bearer $NOXTICA_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"subjectRef":"cust_example","returnUrl":"https://merchant.example.com/verification/return"}'
```

```js
const response = await fetch('https://collect.noxtica.com/v1/kyc/sessions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NOXTICA_SERVER_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    subjectRef: 'cust_example',
    returnUrl: 'https://merchant.example.com/verification/return',
  }),
});

const body = await response.json();
if (!response.ok) throw new Error(`session creation failed: ${response.status} ${body.error}`);

// Store body.sessionId with your customer record, then send body.url to the customer.
```

```python
import json
import os
import urllib.request
import uuid

request = urllib.request.Request(
    "https://collect.noxtica.com/v1/kyc/sessions",
    data=json.dumps(
        {
            "subjectRef": "cust_example",
            "returnUrl": "https://merchant.example.com/verification/return",
        }
    ).encode(),
    headers={
        "Authorization": "Bearer " + os.environ["NOXTICA_SERVER_KEY"],
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    method="POST",
)

with urllib.request.urlopen(request) as response:
    body = json.load(response)

# Store body["sessionId"] with your customer record, then send body["url"] to the customer.
```

## Send the customer to the link

Choose the delivery that fits your journey:

- **Redirect.** Send the customer's browser to `url` as a full page. This is the simplest path.
- **New tab.** Open `url` in a new tab or window from your own page.
- **Email or message.** Send the link through your own channel.
- **QR code.** Show the link as a QR code so the customer can continue on a phone. The hosted page also offers a QR code and a copy-link option for moving to a phone.

What the hosted page does and does not do:

- **It cannot be embedded.** The hosted page refuses to load inside an iframe. Open it as a full page or in a new tab.
- **It does not message your page.** The page does not post a message to the window that opened it, and it does not close itself. Do not wait for a script on your side to learn the outcome.
- **It follows the customer's language.** The language comes from the customer's browser. You cannot set it, and the link accepts no parameters beyond its own path.
- **Some browsers cannot be used.** Some in-app browsers are not supported. The page tells the customer how to continue in their regular browser.

### Return link

The return link is optional.

- Set `returnUrl` when you create the session. Its host must be on your approved return hosts.
- After a completed outcome, the hosted page shows a plain "Return to your business" link to exactly that address. There is no automatic redirect, and no query parameters are added, so the address carries no session id or status.
- The link is not shown after a review, unverified, error, cancelled or expired outcome.
- Invitations created from the Backoffice carry no return link.

Because a finished capture currently waits for a decision, most customers do not reach a return link straight away. Design your journey so that it does not depend on the customer coming back: show your own "we will let you know" state, and finish through the status read or the event. Correlate with the `sessionId` you stored, and never treat a visit to your return page as proof of completion.

### Lifetimes

An unopened link stays valid until its own expiry, one day by default. After the customer first opens the link, the customer has 30 minutes to finish, or until the original expiry if that comes sooner. A session that waits in `review_pending` does not expire while it waits for a decision. [KYC Hosted Sessions](https://noxtica.com/docs/kyc-hosted-sessions/) explains expiry and the `410` responses the hosted page itself returns.

## Get the outcome

Two routes lead to the outcome: a status read, and a signed event. Use both. The event saves you from polling, and the status read is the authority.

### Read the session status

```http
GET https://collect.noxtica.com/v1/kyc/sessions/{sessionId}
Authorization: Bearer sk_prod_your_server_key
```

A session you created always returns `200`, including an expired one, which reads `"status": "expired"`. A session id that does not exist, or that belongs to another organisation, returns `404`.

```json
{
  "ok": true,
  "session": {
    "id": "<uuid>",
    "status": "review_pending",
    "subjectId": "cust_example",
    "expiresAt": 1790763900000,
    "completedAt": 1790762445000,
    "verificationId": "<verification-id>",
    "reasonCodes": ["<reason-code>"],
    "returnUrl": "https://merchant.example.com/verification/return",
    "decision": {
      "outcome": "review_pending",
      "reasonCodes": ["<reason-code>"],
      "decidedAt": 1790762445000
    }
  },
  "requestId": "<request-id>"
}
```

- Everything sits under `session`. `session.id` is the `sessionId` from creation, and `subjectId` is the `subjectRef` you sent.
- Timestamps are epoch milliseconds, or `null` when the moment has not happened.
- `decision` appears once the session has an outcome. Its `outcome` is `approved`, `rejected`, `review_pending` or `error`.
- `verificationId` identifies the verification case, so you can find it in the KYC pages of the Backoffice.
- When Noxtica Verification IDs are enabled for your organisation, the session also carries `nvid`.
- The response can carry more fields than this page lists. Ignore fields you do not use and do not fail on unknown ones.

Poll with a delay that grows between reads and stop at a final status. Do not poll in a tight loop; rate limits apply.

### Statuses

| Status              | Meaning                                                                                                                   | Event                                                                       |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `pending`           | Created. The customer has not opened the link.                                                                            | None                                                                        |
| `opened`            | The customer opened the link and is working through the steps.                                                            | None                                                                        |
| `verifying`         | The customer submitted and processing is running.                                                                         | None                                                                        |
| `review_pending`    | Processing finished and a decision is needed in your Backoffice review queue. Not a rejection, and not an approval.       | None yet. `kyc.session.completed` follows when a decision is recorded.      |
| `completed`         | A decision approved the session.                                                                                          | `kyc.session.completed` with status `completed`                             |
| `unverified`        | Processing finished with a negative outcome.                                                                              | `kyc.session.completed` with status `unverified`                            |
| `error`             | Processing could not finish, because of a fault or a refusal.                                                             | `kyc.session.completed` with status `error`                                 |
| `expired`           | The link or the capture window lapsed before a decision.                                                                  | None. Read the status to observe expiry.                                    |
| `cancelled_by_user` | The customer chose to cancel on the hosted page. This applies when cancelling is enabled for your organisation.           | `kyc.session.cancelled`                                                     |

Only `completed` is an approval. Treat every other status as not approved until you have read a later one.

## Receive events

Events are notifications. They save you from polling, and they are not the decision.

| Event                    | When it is sent                                                                                                                                      |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `kyc.session.completed`  | A session reaches `completed`, `unverified` or `error`. This includes the moment a reviewer decision resolves a `review_pending` session.             |
| `kyc.session.cancelled`  | The customer cancelled on the hosted page. Subscribe to it explicitly. It applies when cancelling is enabled for your organisation.                  |

Other identity event types exist. This page covers the two that describe a hosted session; [Identity verification events and webhooks](https://noxtica.com/docs/identity-verification-webhooks/) lists every identity event, its payload and when it is sent.

Review decisions are relayed on a periodic schedule, so allow a few minutes between a decision and its event. An expired session sends no event: use the status read to observe expiry.

The Backoffice "Send test" button sends a sample of a different event type. It cannot produce an identity event, so test your handler with a signed sample of your own.

Every delivery is an HTTPS `POST` with these headers:

| Header                | Value                                                                  |
| --------------------- | ---------------------------------------------------------------------- |
| `X-Noxtica-Signature` | `sha256=` followed by the lowercase hex signature                      |
| `X-Noxtica-Timestamp` | The time of this attempt, in epoch milliseconds                        |
| `X-Noxtica-Event`     | The event type                                                         |
| `X-Noxtica-Delivery`  | The delivery id, identical to the `id` in the body                     |

The body is a JSON envelope with `id`, `type`, `created_at`, `tenant_id` and `data`. `schemaVersion` sits inside `data`, not on the envelope.

```json
{
  "id": "<sessionId>:<webhookId>",
  "type": "kyc.session.completed",
  "created_at": 1790762445000,
  "tenant_id": "<tenant-id>",
  "data": {
    "schemaVersion": "1",
    "sessionId": "<sessionId>",
    "status": "completed",
    "verificationId": "<verification-id>",
    "reasonCodes": ["<reason-code>"],
    "occurredAt": 1790762445000,
    "deliveryId": "<sessionId>:<webhookId>"
  }
}
```

```json
{
  "id": "<sessionId>:<webhookId>",
  "type": "kyc.session.cancelled",
  "created_at": 1790762300000,
  "tenant_id": "<tenant-id>",
  "data": {
    "schemaVersion": "1",
    "sessionId": "<sessionId>",
    "status": "cancelled_by_user",
    "cancelReason": "not_now",
    "cancelledAt": 1790762300000,
    "occurredAt": 1790762300000,
    "deliveryId": "<sessionId>:<webhookId>"
  }
}
```

- `cancelReason` is `null` or one of `not_now`, `privacy_concern`, `no_document`, `technical_problem` and `other`.
- When Noxtica Verification IDs are enabled for your organisation, a completed event also carries `data.nvid`. Other optional steps can add fields to `data`, so ignore fields you do not recognise.
- Events never carry your `subjectRef`. Match an event to your customer by `sessionId`.

### Verify the signature

The signature is an HMAC-SHA256 with your endpoint's signing secret over the timestamp, a dot, and the raw request body: `${timestamp}.${rawBody}`. Verify it before you parse or trust anything in the body.

- Use the body exactly as received. Do not parse and re-serialise it.
- Compare in constant time.
- Check the timestamp header, not `created_at`. Every retry is signed again with a fresh timestamp.
- Noxtica does not enforce a timestamp window on its side, so enforce your own. Five minutes is a sensible tolerance.

```js
import { createHmac, timingSafeEqual } from 'node:crypto';

const TOLERANCE_MS = 5 * 60 * 1000;

export function verifyNoxticaWebhook({ secret, timestamp, signature, rawBody, now = Date.now() }) {
  const sentAt = Number(timestamp);
  if (!Number.isSafeInteger(sentAt) || Math.abs(now - sentAt) > TOLERANCE_MS) return false;

  const expected = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
  const provided = String(signature).replace(/^sha256=/, '').toLowerCase();

  const expectedBytes = Buffer.from(expected);
  const providedBytes = Buffer.from(provided);
  return expectedBytes.length === providedBytes.length && timingSafeEqual(expectedBytes, providedBytes);
}
```

```python
import hashlib
import hmac
import time

TOLERANCE_MS = 5 * 60 * 1000

def verify_noxtica_webhook(secret: str, timestamp: str, signature: str, raw_body: bytes) -> bool:
    if not (timestamp.isascii() and timestamp.isdigit()):
        return False
    if abs(time.time() * 1000 - int(timestamp)) > TOLERANCE_MS:
        return False

    signed = timestamp.encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    provided = signature.removeprefix("sha256=").lower()
    return hmac.compare_digest(expected, provided)
```

### Delivery, retries and duplicates

- A `2xx` response marks the delivery as delivered.
- Any `4xx` response is final. The delivery is not retried, including `408` and `429`. Return a `4xx` only when you mean it.
- A redirect, a `5xx` response, a timeout or a network error is retried, up to five more attempts. After that the delivery is marked failed and is not sent again. The retry spacing is not published, so do not build on it.
- Each attempt waits up to five seconds for your response, and redirects are not followed. Acknowledge quickly and process afterwards.
- Delivery is at least once. Deduplicate on `X-Noxtica-Delivery`, which stays the same across retries.
- Order is not fixed. Two events for the same session can arrive in either order.

### A notification is not authority

When an event arrives, verify it, record the delivery id, and then read `GET /v1/kyc/sessions/{sessionId}`. Act on the `status` that read returns, not on the event body. This keeps your state correct when events are late, repeated or out of order, and it means a forged or replayed event cannot approve anyone.

## Noxtica Verification ID

When Noxtica Verification IDs are enabled for your organisation, a session that completes or waits for review is given an ID in the form `NVID-XXXX-XXXX-XXXX-XXXX`. The customer sees it on the final page, and you read it from `session.nvid` or `data.nvid`. The ID is not a credential and does not sign anyone in. A person who has it can check its status on the verification site. That public lookup accepts requests only from the verification site itself, so your server cannot call it: read the ID from the session status or the event instead.

## Errors

Every error body is JSON and includes a `requestId`. Quote it when you contact support.

| Status | Error                                     | Meaning                                                                                              | What to do                                                                                                   |
| ------ | ----------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `400`  | `invalid_request`                         | Malformed JSON, a missing or over-long `subjectRef`, a bad `expiresInSeconds`, `purpose` or `Idempotency-Key`. | Fix the request. Check field names and limits.                                                               |
| `400`  | `invalid_hosted_options`                  | `hostedOptions` is not a complete, valid object.                                                     | Send the complete object or leave it out.                                                                    |
| `400`  | `invalid_id_type`                         | `idType` is not accepted for this session.                                                           | Leave `idType` out.                                                                                          |
| `400`  | `return_url_not_allowed`                  | `returnUrl` is not `https` or its host is not an approved return host.                               | Add the host in the hosted page settings or leave `returnUrl` out.                                           |
| `400` or `403` | an error ending in `_not_enabled`, or `email_verification_unavailable` | You asked for an optional step that is not enabled for your organisation.       | Leave that step out of `hostedOptions`, or ask your account team.                                            |
| `401`  | `invalid_api_key`                         | The key is missing, malformed, unknown or revoked.  | Check the `Authorization` header, and that the key matches the environment you call.                         |
| `403`  | `API key does not have write:identity scope` | The key lacks the identity permission.                                                            | Create a key with "Verify identity documents (KYC)" ticked.                                                  |
| `403`  | `kyc_legal_basis_receipt_required`        | Your organisation has not recorded the legal basis for hosted identity verification.                 | Record it in the Backoffice, then retry.                                                                     |
| `404`  | `V1 endpoint not found`                   | The module is not provisioned for your tenant, or the path is wrong. A status read also returns it for an unknown session id. | Check the path and session id. If both are right, ask your account team. Do not retry in a loop. |
| `413`  | `body_too_large`                          | The request body is too large.                                                                       | Send a small JSON object.                                                                                    |
| `415`  | `invalid_request`                         | The `Content-Type` is not JSON.                                                                      | Send `Content-Type: application/json`.                                                                       |
| `429`  | `Rate limit exceeded`                     | Too many requests.                                                                                   | Back off and retry. Honour `retryAfter` or `Retry-After` when present.                                       |
| `500`  | `server_misconfigured`                    | A server-side configuration problem.                                                                 | Contact support with the `requestId`.                                                                        |
| `503`  | `tenant_module_gate_unavailable`, `kyc_legal_basis_receipt_unavailable`, `invalid_request` with a `reason` | A temporary fault.                                       | Retry with a growing delay, and honour `Retry-After` when present.                                           |
| `503`  | `hosted_verify_not_configured`            | The hosted verification service is not set up for this environment.                                  | Contact your account team.                                                                                   |

A status read can also return `400` with `Invalid sessionId` when the id cannot be decoded.

The shared error envelope, rate limits and key handling are described in [Errors](https://noxtica.com/docs/api/errors/) and [Authentication](https://noxtica.com/docs/api/authentication/).

## Who it fits

Use identity verification where your policy requires identity evidence and a person on your team owns the review.

- **Onboarding and account opening.** Collect supported identity evidence through a hosted flow, without building your own capture screens.
- **Exceptions and review queues.** Separate finished, expired, cancelled, and needs-review cases (see [Statuses](https://noxtica.com/docs/identity-verification-integration/#statuses)). Keep the exception path visible to your operators.
- **Deciding when to ask.** Pair verification with Device Intelligence and Risk Scoring to decide which journeys call for identity evidence. [Common questions](https://noxtica.com/docs/identity-verification-integration/#common-questions) explains how they differ.

## How teams connect

Identity verification has three surfaces: the server API, the hosted page, and the console with events. [Choose how to integrate](https://noxtica.com/docs/identity-verification-integration/#choose-how-to-integrate) shows which route fits your team. Operators set up the hosted page in [Invitations and hosted verification settings](https://noxtica.com/docs/identity-verification-invitations/), and your endpoints subscribe to session events as described in [Identity verification events and webhooks](https://noxtica.com/docs/identity-verification-webhooks/).

## Limits

Read these boundaries before you design the flow.

- **Controlled availability.** What applies depends on an eligible identity configuration, your jurisdiction, and your contract. Confirm with your account team before you plan around it. See [Availability](https://noxtica.com/docs/identity-verification-integration/#availability).
- **Not legal identity proof.** No result is legal identity proof outside the scope of the configured provider and contract. Results are probabilistic and can include false positives and false negatives. They are not statements of fact. Read the [disclaimer](https://noxtica.com/disclaimer/).
- **You decide.** A qualified person on your team should review adverse decisions. Noxtica is not a consumer reporting agency. Do not use output for credit, insurance, employment, or housing eligibility.
- **Your responsibilities.** You own the notices, consents, and legal basis for collecting identity evidence from your customers in each jurisdiction you serve. Plan a fallback for sessions that expire, are cancelled, or end in an error. The [Privacy Policy](https://noxtica.com/privacy/) and the [Security page](https://noxtica.com/docs/security/) describe how Noxtica handles personal data; no module-specific data-scope statement for identity verification is published yet.

## Common questions

Answers about statuses, review, links, keys, events and the Verification ID are in [Identity verification FAQ and troubleshooting](https://noxtica.com/docs/identity-verification-faq/). Two product questions are not covered there.

### Can I turn identity verification on myself?

No. It is provisioned per tenant under Controlled availability; see [Availability](https://noxtica.com/docs/identity-verification-integration/#availability). Contact your account team to discuss your use case and jurisdiction.

### How does it relate to Device Intelligence and Risk Scoring?

They answer different questions. Device and risk evidence describe a browser context and an interaction. Identity verification gathers evidence about a person for your decision. Device risk can support identity evidence, but neither replaces the other.

## Go-live checklist

- The readiness checklist in the Backoffice KYC pages shows no missing item, and a test session runs end to end.
- The legal basis is recorded by an authorised person in your organisation, and the notices and consents you owe your customers are in place.
- The server key has the identity permission, lives in a server secret store, and is never sent to a browser or an app.
- Your server creates every session, sends an `Idempotency-Key`, stores the `sessionId` with the customer, and never logs the link.
- Your return page makes no assumption about the outcome, and your journey works when the customer never comes back.
- Your events endpoint uses HTTPS, verifies the signature over the raw body, enforces a timestamp tolerance, deduplicates on the delivery id, answers quickly and reads the session status before it acts.
- A scheduled status read covers sessions that send no event, such as an expired session or one in `review_pending`.
- Your code handles every status. Only `completed` is an approval, and `review_pending` is neither an approval nor a rejection.
- A person in your organisation reviews any adverse decision before it affects a customer. Results can be wrong in either direction and are not legal proof of identity.
- Noxtica does not delete verification details or evidence automatically and sets no retention date for them: they stay until a tenant administrator deletes them. [Verification data: storage, access and deletion](https://noxtica.com/docs/identity-verification-data/) explains how an administrator deletes a verification in Backoffice.
- The [Privacy Policy](https://noxtica.com/privacy/) and the [Security page](https://noxtica.com/docs/security/) describe how Noxtica handles personal data. This page does not.

## Related reading

- [Invitations and hosted verification settings](https://noxtica.com/docs/identity-verification-invitations/) — the Backoffice settings every hosted link uses, and invitations without code.
- [Self-hosted identity verification (direct API)](https://noxtica.com/docs/identity-verification-self-hosted/) — the direct API as it works today.
- [Identity verification events and webhooks](https://noxtica.com/docs/identity-verification-webhooks/) — every identity event and its payload.
- [Noxtica Verification ID (NVID)](https://noxtica.com/docs/identity-verification-id/) — the shareable reference for a verification.
- [Identity verification FAQ and troubleshooting](https://noxtica.com/docs/identity-verification-faq/) — answers to the questions integrators ask most.
- [KYC Hosted Sessions](https://noxtica.com/docs/kyc-hosted-sessions/) — session lifetime, expiry and the `410` responses.
- [Backend Integration](https://noxtica.com/docs/backend-integration/) — keep the credential on your server and handle explicit response states.
- [Identity verification](https://noxtica.com/products/identity-verification/) — the product overview, availability and limits.

---

Source: https://noxtica.com/docs/identity-verification-self-hosted/
Markdown: https://noxtica.com/docs/identity-verification-self-hosted/index.md
Last updated: 2026-10-27

# Self-hosted identity verification (direct API)

This guide is for a backend engineer who wants to start identity verifications from a server without a link and without the page Noxtica hosts. Your server calls the direct API, receives a verdict, reason codes and a verification id, and keeps them next to your own customer record.

Read the limits first. The direct route is a smaller surface than hosted sessions, and one thing does not work today: it gives your own screens no way to capture a document and have it checked. The section "Capture in your own application" says exactly why and what to use instead.

## What it is

Availability: Controlled availability. Identity verification is provisioned per tenant by your account team, and the account team confirms which of the routes below apply to your tenant. See the [product page](https://noxtica.com/products/identity-verification/) for the overview and the limits of the result.

The direct API is a set of server-to-server routes under `https://collect.noxtica.com/v1/kyc/`. Every call uses your server key as a bearer token. What it provides today:

- **Admission and result.** `POST /v1/kyc/verify` mints a single-use nonce (`action: "mint"`), then runs one verification with that nonce (`action: "verify"`). The response carries a verdict, a verification level, reason codes and a `verificationId`.
- **Safe retries.** A repeated call with the same `Idempotency-Key` returns the stored response again instead of running a second verification.
- **Re-check a known subject.** `POST /v1/kyc/reverify` asks whether a subject is already verified, to at least a level you name, using your tenant's device registry.
- **Bulk admission.** `POST /v1/kyc/verify/batch` admits up to 500 rows from a JSON or CSV manifest, with status, results and cancel routes.
- **Evidence for a verification that already exists.** `POST /v1/kyc/evidence/handle` and `POST /v1/kyc/evidence/finalize` upload sealed evidence for an admitted verification. A proof-of-address cross-match builds on that upload.
- **An event when a verification finishes.** `kyc.verification.completed`, described in [Identity verification events and webhooks](https://noxtica.com/docs/identity-verification-webhooks/).

Results are automated signals. You decide what each outcome means for your customer, and a person in your organisation should review any adverse decision before it affects someone.

## Capture in your own application

Documents are captured on the page Noxtica hosts. The direct API does not replace that page, for two reasons you can check against the routes above:

- A verify request carries data only. It does not accept images, audio or other media, and the request body is limited to 32 KiB.
- An evidence handle is issued only for a verification that already exists in your tenant. The verify call creates that verification and returns its id in the same request that runs the check, so your application has no moment in which to upload a capture and then run the document check on it.

Until a route for this exists, use [hosted identity verification](https://noxtica.com/docs/identity-verification-integration/) when the customer must capture a document, or send an invitation from Backoffice ([Invitations and hosted verification settings](https://noxtica.com/docs/identity-verification-invitations/)). This section is where a future route for capture in your own application will be documented; nothing on this page promises one.

Plan your code for what the current document check returns. It hands its result to a person for review and reports the reason code `provider_manual_review`, so expect `unverified` together with that reason rather than an automatic `verified`. Handle every verdict.

## Prerequisites

- **The module is provisioned for your tenant.** Until it is, every route below returns the plain `404` with the body `V1 endpoint not found`. Two switches have to be on (a platform switch and your tenant's module), and the response is identical whichever one is off, so a `404` means "ask your account team", not "retry".
- **A server key with the identity permission.** In Backoffice open API & SDK → Server API Keys and create a key with "Verify identity documents (KYC)" ticked. A new key does not carry it by default. The secret is shown once; keep it in your server secret store and never in a browser or an app.
- **For evidence routes only:** raw evidence storage armed for your tenant and a data residency (`TR`, `EU` or `US`) set for it. Ask your account team. A request whose `jurisdiction` does not match your tenant's residency gets the same plain `404`.
- **A recorded legal basis where your organisation is required to have one.** Without it the verify route answers `403 kyc_legal_basis_receipt_required`. An authorised person records it in Backoffice → Identity Verification → KYC Invitations → Settings.

## Steps

### 1. Mint an admission nonce

The nonce is single-use, tied to your tenant and valid for 300 seconds. Mint it as close to the verify call as you can.

```bash
curl -sS -X POST https://collect.noxtica.com/v1/kyc/verify \
  -H "Authorization: Bearer $NOXTICA_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "mint" }'
```

```json
{ "ok": true, "nonce": "<nonce>", "ttlSeconds": 300 }
```

### 2. Run the verification

Send the nonce within its lifetime, with an `Idempotency-Key` header of 8 to 128 characters. A missing or malformed key is rejected with `400 invalid_request` before anything runs.

```bash
curl -sS -X POST https://collect.noxtica.com/v1/kyc/verify \
  -H "Authorization: Bearer $NOXTICA_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "action": "verify",
    "nonce": "<nonce>",
    "id_type": "passport",
    "purpose": "identity_verification"
  }'
```

```js
import { randomUUID } from 'node:crypto';

const base = 'https://collect.noxtica.com';
const headers = {
  Authorization: `Bearer ${process.env.NOXTICA_SERVER_KEY}`,
  'Content-Type': 'application/json',
};

const mint = await fetch(`${base}/v1/kyc/verify`, { method: 'POST', headers, body: JSON.stringify({ action: 'mint' }) });
if (!mint.ok) throw new Error(`mint failed: ${mint.status}`);
const { nonce } = await mint.json();

const idempotencyKey = randomUUID(); // store it with the customer; reuse it only to retry this same request
const verify = await fetch(`${base}/v1/kyc/verify`, {
  method: 'POST',
  headers: { ...headers, 'Idempotency-Key': idempotencyKey },
  body: JSON.stringify({ action: 'verify', nonce, id_type: 'passport', purpose: 'identity_verification' }),
});
const result = await verify.json();
if (!verify.ok) throw new Error(`verify failed: ${verify.status} ${result.error}`);
// Store result.verificationId with your customer record. Read the verdict below.
```

| Field | Required | Notes |
| --- | --- | --- |
| `action` | No | `mint` or `verify`. When you leave it out the request is treated as `verify`. |
| `nonce` | Yes | From the mint call. Used once. A missing nonce is rejected with `400 missing_nonce`. |
| `id_type` (or `idType`) | Yes | The document type your customer presents. A missing value is rejected with `400 invalid_request`. |
| `purpose` | No | Defaults to `identity_verification`. Other values come from a closed list; an unknown value can be rejected with `400 invalid_request`. |
| `payload` | No | Data only, never media. What a payload may contain depends on the configured check; leave it out unless your account team specifies one. |
| `deviceContext` | No | `true` adds an advisory `deviceTrust` block to the response. |

A request that includes an `attachDeviceTrust` field, in any shape, is rejected with `400`: device trust cannot be asserted by the caller.

### 3. Read and store the result

A verdict is always returned with status `200`. A fault on Noxtica's side comes back as `"verdict": "error"`, never as a subject statement and never as a `5xx`.

```json
{
  "ok": true,
  "verdict": "unverified",
  "verificationLevel": "partial",
  "reasonCodes": ["provider_manual_review"],
  "verificationId": "<verification-id>",
  "requestId": "<request-id>"
}
```

| Field | Meaning |
| --- | --- |
| `verdict` | `verified`, `unverified` or `error`. Act on `verified` as an approval only after your own checks; treat everything else as not approved. |
| `verificationLevel` | `verified`, `partial`, `unverified` or `inconclusive`. |
| `reasonCodes` | Closed-list codes that explain the outcome. Branch on codes, never on text, and ignore codes you do not know. |
| `verificationId` | Identifies the verification. Find it in Backoffice under Identity Verification → KYC Verifications. |
| `requestId` | Quote it when you contact support. |

A tenant policy that blocks or challenges can turn a provider `verified` into `unverified` and add `policy_blocked` or `policy_challenge_required` to the reason codes.

A repeated request with the same `Idempotency-Key` returns the stored response byte for byte, with no second verification. A different body under a key you already used is refused with `409 idempotency_conflict`. A request still running under that key answers `409` with the reason code `request_in_progress`; wait and retry with the same key.

### 4. Choose how you learn about later changes

`POST /v1/kyc/verify` answers when the check ends, so you do not need to poll for the result of that call. A verification that reaches a final state also sends a signed event, `kyc.verification.completed`. Register an endpoint under Integrations → Webhooks and verify the signature as described in [Identity verification events and webhooks](https://noxtica.com/docs/identity-verification-webhooks/). Treat the event as a notification: compare it with the verification you stored before you act. A person's review decision is visible in Backoffice under Identity Verification → KYC Review Queue and Identity Verification → KYC Verifications.

### 5. Re-check a subject you verified before (optional)

`POST /v1/kyc/reverify` answers one question: is this subject already verified, in your tenant's device registry, to at least the level you ask for. It needs the same key permission and a device registry module that your account team enables, it takes the opaque subject identifier your records use for the customer, and it always returns `200`.

```bash
curl -sS -X POST https://collect.noxtica.com/v1/kyc/reverify \
  -H "Authorization: Bearer $NOXTICA_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "subjectId": "cust_example", "requiredLevel": "verified" }'
```

```json
{ "ok": true, "verified": true, "verificationLevel": "verified", "requestId": "<request-id>" }
```

A missing `subjectId` or an unknown `requiredLevel` is rejected with `400 invalid_request`.

### 6. Admit rows in bulk (optional)

`POST /v1/kyc/verify/batch` accepts a JSON manifest (`{ "items": [{ "idType": "passport" }] }`) or a CSV with an `id_type` column, up to 500 rows and 256 KiB, with a required `Idempotency-Key` header. It answers `202` with a `batchId` and one status per row. Read progress with `GET /v1/kyc/verify/batch/{batchId}/status` and per-row outcomes with `GET /v1/kyc/verify/batch/{batchId}/results`, and stop work that has not started with `POST /v1/kyc/verify/batch/{batchId}/cancel`. The field-level reference is in the [identity API reference](https://noxtica.com/docs/api/reference/kyc/).

### 7. Attach evidence to an admitted verification (optional)

Evidence is uploaded as sealed ciphertext: `POST /v1/kyc/evidence/handle` returns a short-lived handle and the keys to seal with, and `POST /v1/kyc/evidence/finalize` redeems it. Your code does the sealing, so plan time for it and read the [identity API reference](https://noxtica.com/docs/api/reference/kyc/) before you start. The handle is valid for 15 minutes. Evidence kinds are a closed list, and kinds that the platform derives itself are refused with `400 invalid_request`.

## Verify it works

- The mint call returns `"ok": true` and a nonce, and the verify call returns status `200` with a `verificationId`.
- Repeating the verify call with the same `Idempotency-Key` and body returns the same response.
- The verification appears in Backoffice under Identity Verification → KYC Verifications with the `verificationId` you stored.
- If you registered an endpoint, your handler receives `kyc.verification.completed` with a valid signature.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| `404` with `V1 endpoint not found` | The module is not provisioned for your tenant, the path is wrong, or an evidence request named a residency other than your tenant's. | Check the path, then ask your account team. Do not retry in a loop. |
| `401 invalid_api_key` | The key is missing, malformed, unknown or revoked. | Check the header and that the key is a current `sk_prod_` key. |
| `403` with `API key does not have write:identity scope` | The key lacks the identity permission. | Create a key with "Verify identity documents (KYC)" ticked. |
| `403 kyc_legal_basis_receipt_required` | Your organisation has no recorded legal basis. | Record it in Backoffice, then retry. |
| `403 tenant_inactive` | The tenant is suspended. | Contact your account team. |
| `400 missing_nonce` | The verify body has no nonce. | Mint a nonce and send it. |
| `400 invalid_request` | A missing `Idempotency-Key` or `id_type`, a malformed `purpose`, an `attachDeviceTrust` field, or evidence of a kind you may not upload. | Fix the request. |
| Verdict `unverified` with `provider_manual_review` | The check handed the result to a person. | A reviewer decides in Backoffice under Identity Verification → KYC Review Queue. |
| Verdict `error` | A fault on the verification side, not a statement about the subject. | Retry with a new nonce and a new `Idempotency-Key`. |
| `402 spend_cap_reached` | Your organisation's spending limit is reached. | Contact your account team. |
| `409 idempotency_conflict` | The key was used with a different request. | Use a new key for a new request. |
| `413 body_too_large` or `415 invalid_request` | The body is over the limit or not JSON. | Send a small JSON body with `Content-Type: application/json`. |
| `429 Rate limit exceeded` | More than 10 calls in 60 seconds with one key on these routes. | Back off and retry. Honour `Retry-After` when present. |
| `503 kyc_verify_unavailable` | A temporary fault. | Retry after the `Retry-After` delay. |

The shared error envelope and the rate-limit rules are described in [Errors](https://noxtica.com/docs/api/errors/) and [Authentication](https://noxtica.com/docs/api/authentication/).

## Related

- [Identity verification integration](https://noxtica.com/docs/identity-verification-integration/): hosted sessions, the route that captures documents for you.
- [Invitations and hosted verification settings](https://noxtica.com/docs/identity-verification-invitations/): send a hosted link from Backoffice without code.
- [Identity verification events and webhooks](https://noxtica.com/docs/identity-verification-webhooks/): every identity event and its payload.
- [Verification data: storage, access and deletion](https://noxtica.com/docs/identity-verification-data/): how verification data is kept and deleted.
- [Identity API reference](https://noxtica.com/docs/api/reference/kyc/): the generated field-level reference.

---

Source: https://noxtica.com/docs/identity-verification-invitations/
Markdown: https://noxtica.com/docs/identity-verification-invitations/index.md
Last updated: 2026-10-27

# Invitations and hosted verification settings

Every hosted verification link, whether your server creates it by API or a person creates it in Backoffice, shows the customer the page you configure under **Identity Verification → KYC Invitations → Settings**. This guide takes an administrator from an empty configuration to a working invitation, and a reviewer through reading the result. You do not write code for anything on this page.

If your server creates the links, set up the Settings tab here first and then follow [Identity verification integration](https://noxtica.com/docs/identity-verification-integration/).

## What it is

Availability: Controlled availability. Identity verification is provisioned per tenant by your account team; see the [product page](https://noxtica.com/products/identity-verification/) for the overview and the limits of the result.

The **KYC Invitations** page in Backoffice (route `/kyc/invitations`, in the Identity Verification group of the navigation) has three tabs. The active tab is kept in the address as `?tab=history`, `?tab=active` or `?tab=settings`.

| Tab | What it is for |
| --- | --- |
| History (the default) | The durable list of every invitation your tenant has started, plus a lookup by session id. |
| Active invitations | The one-time links you started in this browser tab. Links are shown here once and are not saved anywhere else. |
| Settings | The setup status, the verification steps, the hosted page configuration and the legal basis. |

Who can do what:

- An analyst or above can open the page and read the History tab.
- An administrator can create invitations, save the hosted configuration and record the legal basis. Creating an invitation and saving the configuration each ask for a fresh step-up verification of the signed-in person.
- Anyone who sees "KYC verification is not enabled" is working in a tenant whose module is not provisioned yet. Ask your account team.

A link created here carries no return link: after the customer finishes there is no "Return to your business" button. Return links belong to sessions created by API. Invitations created here cannot be re-sent or revoked from the page. When a link is lost or should no longer be used, start a new invitation and let the old one expire.

## Prerequisites

- **The identity verification module is provisioned** for your tenant. The Settings tab lists it at the top of the setup status when it is missing.
- **An administrator account** with fresh step-up verification available. A viewer or analyst can read but cannot create or save.
- **The text your customers will see:** your business name, the purpose of the verification in one plain sentence, the address of your privacy notice (a complete `https` address), a version label for that notice, and the documents you accept with their issuing countries.
- **The legal basis your organisation relies on.** An authorised person in your organisation records it. Noxtica does not choose one for you.
- **Optional:** the host names of your own pages if API-created sessions should offer a return link, a server key and an events endpoint if your server will also create sessions ([Identity verification integration](https://noxtica.com/docs/identity-verification-integration/)).

## Steps

### 1. Open the Settings tab and read the setup status

Open Backoffice → Identity Verification → KYC Invitations → Settings. The setup status lists what is done and what is missing, and each open row links to the control that fixes it.

| Row | What it checks |
| --- | --- |
| KYC verification module | The module is active for your organisation. |
| Hosted verification links | The deployment can issue signed hosted links. A message here means something only Noxtica operates is not ready; contact your account team. |
| Hosted verification page | Business name, privacy notice and accepted documents are saved. |
| Legal basis | An active legal basis covers hosted identity verification. |
| Return destination | Optional. A host name approved for return links on API-created sessions. |
| Server API key | Optional. A server key with the identity permission exists. |
| Webhook endpoint | Optional. An endpoint receives identity events. |

Until the required rows are done, a customer who opens a link sees "Verification isn't ready yet", and Backoffice does not let you create invitations.

### 2. Fill in the hosted verification configuration

Select **Edit configuration**. The form is prefilled and shows a customer preview beside it. Each prefilled value is labelled **Saved**, **From your workspace** or **Suggested — check it**, so you can see where it came from and confirm it before you save. When a value is wrong, for example an address without `https://`, the message under the field names the exact correction and offers it as one click. Fields marked with an asterisk are required.

| Field | Required | What it does |
| --- | --- | --- |
| Business name | Yes | The organisation name at the top of the verification page. |
| Verification purpose | Yes | A plain-language reason shown before the customer agrees to continue. |
| Privacy policy URL | Yes | A complete `https` address. The form tells you when a scheme is missing or wrong. |
| Privacy notice version | Yes | A short version or date that customers and audit records can identify. |
| Support URL | No | An `https` address for customers who need help. |
| Supported documents | Yes | Each document a customer may use, with its issuing countries as two-letter codes such as `TR` or `GB`. Select at least one. |
| Verification checks and mode settings | Per form | The remaining switches in the "Verification checks" section. The setup status and the Verification steps guide show what each does for your organisation. |
| Email verification | No | Whether customers confirm an email address: Off, Optional or Required. It applies to every link unless you choose otherwise when creating one, and is offered only when enabled for your organisation. |
| Allowed return hosts | No | Host names only, with no `https://`, path, port or wildcard. Used by API-created sessions that carry a `returnUrl`. |

Select **Save configuration**. Saving asks for a fresh step-up verification. The form shows the time of the last update.

### 3. Review the verification steps

The **Verification steps** guide on the same tab lists every step the hosted page can ask a customer to complete, whether it is on for your organisation, and a link to the control that switches it on. A step marked "Per invitation" is chosen each time you create an invitation. A step marked unavailable needs something Noxtica operates, or an approval of your own, before it can be used.

### 4. Record the legal basis

In the Legal basis section of the same tab, an authorised person records the lawful basis your organisation relies on for the hosted capture surface, and the additional condition your counsel requires, if any. Recording, superseding and revoking are separate actions and each is listed with its date. Until a basis is active, customers cannot submit a verification and an API-created session is refused with `kyc_legal_basis_receipt_required`.

### 5. Try it with a test invitation

In the configuration editor, use **Save & send test invitation to myself**. It saves the form, then starts an invitation for you under a customer reference that begins with `test-operator-`, so you can open it on your own device and see what a customer sees. The Integration tab's setup guide offers the same action as **Create a test invitation**. It is a real invitation: it appears in History and a finished capture waits in the review queue like any other.

### 6. Send a real invitation

1. Select **New invitation**.
2. Enter a **Customer reference**: your own opaque reference, 1 to 256 characters. Use an identifier from your system, not a name or a document number.
3. Choose the **Document type**.
4. Optional: set **Expires in (minutes)**. Leave it blank for the default of 24 hours. The accepted range is 5 to 10080 minutes; a value outside it is refused.
5. Optional: choose the email verification mode for this link. "Use organisation default" follows your configuration.
6. Select **Start verification**.

The page switches to Active invitations and shows the one-time link with a copy button and a QR code. Copy it now: it is shown once, in this browser tab, and is not saved. Send it to the customer through your own channel or show the QR code so the customer can continue on a phone.

A request is refused with "This organisation hasn't finished setting up KYC verification" (`kyc_not_ready`) when the setup status still shows a required row open.

### 7. Follow the invitation and read the result

Open the History tab. Each row shows the invitation status, its expiry and, once the customer cancels, the time and the reason they gave. The statuses are the same as in the session status read: `pending`, `opened`, `verifying`, `review_pending`, `completed`, `unverified`, `error`, `expired` and `cancelled_by_user`.

- Use **Check invitation status by id** when a session id reaches you outside the list, for example in a support ticket.
- A finished capture currently waits as `review_pending`. Select **Review this verification** to open the case under Identity Verification → KYC Verifications, or work from Identity Verification → KYC Review Queue. A reviewer with the manage permission and fresh step-up verification records the decision.
- "Completion is not the same as approval": an invitation that finished without a linked verification has nothing to review yet.

To be told when a decision is recorded, register an endpoint under Integrations → Webhooks and subscribe it to identity events ([Identity verification events and webhooks](https://noxtica.com/docs/identity-verification-webhooks/)).

## Verify it works

- The setup status shows no open required row, and the preview shows your business name and privacy notice.
- Your test invitation opens on your own device and shows your business name; the History tab lists it as `opened` and later `review_pending` or another final status.
- A real invitation appears in History within moments of **Start verification**.
- If you registered an endpoint, it receives an identity event after a decision.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| "KYC verification is not enabled" | The module is not provisioned for this tenant. | Ask your account team. |
| The customer sees "Verification isn't ready yet" | The hosted page is not configured or no legal basis is active. | Complete the open rows in the setup status. |
| **New invitation** is disabled or refused with `kyc_not_ready` | A required setup row is still open. | Open the Settings tab and fix the rows it lists. |
| "Enter a valid expiry in minutes" (`invalid_ttl`) | The expiry is empty text, zero, negative or outside 5 to 10080 minutes. | Enter a number inside the range or leave it blank. |
| The form will not save | A required field is empty, the privacy address is not a complete `https` address, or a document has no issuing country. | Follow the message under the field; it names the exact fix. |
| The page asks for step-up again | Creating invitations and saving settings need a fresh check. | Complete it and repeat the action. |
| A link was lost | Links are shown once and cannot be shown again or revoked from the page. | Start a new invitation. |
| "Email verification is not available" | The option is not enabled for your organisation. | Choose "Use organisation default" or "Off", or ask your account team. |
| A message says the deployment cannot create hosted links | Something only Noxtica operates is not ready. | Contact your account team with the time of the attempt. |

## Related

- [Identity verification integration](https://noxtica.com/docs/identity-verification-integration/): create hosted sessions from your server.
- [Self-hosted identity verification (direct API)](https://noxtica.com/docs/identity-verification-self-hosted/): the direct API and its limits today.
- [Identity verification events and webhooks](https://noxtica.com/docs/identity-verification-webhooks/): every identity event and its payload.
- [Verification data: storage, access and deletion](https://noxtica.com/docs/identity-verification-data/): where verification data lives and how it is deleted.
- [KYC Hosted Sessions](https://noxtica.com/docs/kyc-hosted-sessions/): link lifetime, the capture window and expiry.

---

Source: https://noxtica.com/docs/kyc-hosted-sessions/
Markdown: https://noxtica.com/docs/kyc-hosted-sessions/index.md
Last updated: 2026-10-27

# KYC Hosted Sessions

A hosted KYC session is a one-shot verification link your backend mints server-side and hands to your end customer (redirect, email, or QR). The customer completes identity verification on Noxtica's hosted page; your backend never receives the session's bearer token or the customer's raw answers directly.

## Session lifetime

An unopened link keeps its normal default validity. Once the customer opens it, the capture window narrows to **30 minutes from that first open** — not from when your backend minted the link. Both the customer-facing session view and your backend's own session status read carry `openedAt` (when the customer first opened the link, or absent if they have not yet) and `expiresAt` (the session's current effective expiry), so either side can tell which state a session is in without guessing.

## After expiry

Once a session's capture window lapses, its 5 customer-facing routes — session view, progress, submit, evidence upload, and evidence finalize — each return an HTTP `410 Gone` with:

```json
{ "error": "session_expired", "code": "kyc_session_expired", "requestId": "..." }
```

Your backend's own session status read (`GET /v1/kyc/sessions/{sessionId}`) is **not** one of these: it keeps returning `200` with `status: "expired"`, so a polling backend can observe the terminal state without special-casing an error response.

Treat a `410` from any customer-facing route as terminal: stop polling or retrying against that session, and mint a new one if the customer still needs to complete verification.

## Related reading

- [Identity verification integration](https://noxtica.com/docs/identity-verification-integration/) — create a session, send the customer to the link, and read the outcome by status read or signed event.
- [Backend Integration](https://noxtica.com/docs/backend-integration/) — keep the credential on your server and handle explicit response states.
- [Integration Flow](https://noxtica.com/docs/integration-flow/) — trace a full evaluation from collection to customer policy.

---

Source: https://noxtica.com/docs/identity-verification-id/
Markdown: https://noxtica.com/docs/identity-verification-id/index.md
Last updated: 2026-10-27

# Noxtica Verification ID (NVID)

A Noxtica Verification ID (NVID) is a short reference that a hosted identity verification session receives when it completes or waits for review. Your customer sees it on the final hosted screen, your server reads it from the session, and anyone who holds it can check its status on a public page that shows no personal data. Backend engineers read it, and Backoffice administrators revoke or resend it.

## What it is

Availability: Controlled availability. The NVID is part of identity verification, and Noxtica issues it when it is enabled for your organisation. Your account team confirms whether it applies to you.

An NVID looks like `NVID-XXXX-XXXX-XXXX-XXXX`. It has 16 characters from the Crockford base32 alphabet (digits and letters, without I, L, O and U), and the last character is a check character, so most typing mistakes are rejected before any lookup.

| Fact | Detail |
| ---- | ------ |
| When it is issued | When a hosted session ends `completed` or `review_pending`. A session that ends `unverified` or `error` gets none, and neither does an expired or cancelled one. |
| How many | One NVID per session. It is never rotated or re-issued. |
| Validity | `verified` for 365 days from the session's completion time. For a session that waited in review, that time is when a reviewer's decision completed it. The status is worked out when it is read. |
| What it is not | It is not a credential and does not sign anyone in. It carries no personal data. Holding an NVID proves nothing about the person who presents it, because anyone with the ID can read its status. |

The public status is one of four values:

| Status | Label on the status page | Meaning |
| ------ | ------------------------ | ------- |
| `verified` | Verified | The session is `completed` and the validity period has not ended. |
| `pending` | Pending review | The session is in `review_pending`. It is not verified yet. |
| `expired` | Expired | The validity period has passed. |
| `revoked` | Revoked | An administrator revoked the ID. Revoked wins over every other status. |

Results are signals. An NVID shows that a verification happened and what its status is. You still decide what it means for your customer.

## Prerequisites

- Identity verification provisioned for your organisation, and Noxtica Verification IDs enabled for it. When they are not enabled, the status read has no `nvid` key and the hosted screen shows no ID.
- A server key with the identity permission to read the session status. See [Identity verification integration](https://noxtica.com/docs/identity-verification-integration/).
- To see the NVID in Backoffice: a user who can open KYC Verifications. To revoke or resend: a user with the administrator role who can complete step-up verification (MFA).
- For the optional "email me my ID" form: email delivery set up for your environment. Backoffice shows "Email delivery is not configured for this environment" when it is not.

## Steps

### 1. Read the NVID from your server

Read the session status (`GET https://collect.noxtica.com/v1/kyc/sessions/{sessionId}`) and take `session.nvid`:

```json
{
  "ok": true,
  "session": {
    "id": "<uuid>",
    "status": "review_pending",
    "nvid": "NVID-XXXX-XXXX-XXXX-XXXX"
  },
  "requestId": "<request-id>"
}
```

Other `session` fields are left out of this excerpt.

- `nvid` is a string once an ID exists, and `null` when the session has none.
- The key is absent when NVIDs are not enabled for your organisation.
- A `kyc.session.completed` event carries `data.nvid` when an ID was issued. A revoke sends no event, so read the public status when you need the current one.
- Store the NVID next to your `sessionId`. Your `subjectRef` never goes to the public page.

### 2. Let your customer keep it

On the final hosted screen the customer sees "Your Noxtica Verification ID" with the ID, a "Copy ID" button, the current status and an "Open the status page" link. The screen explains that anyone the customer gives the ID to can open the status link, and that the link shows no personal data.

The screen can also offer "Email me my ID (optional)". The customer must tick an unticked consent box before "Send my ID" becomes active. Noxtica sends the ID and the status link to that address. The address is not shown to you. The hosted page accepts up to 3 sends per session, at least 60 seconds apart.

### 3. Share the status link

The status page is `https://verify.noxtica.com/v/<NVID>`. Open it in a browser. It shows:

- the ID and its status, with a plain-language line such as "This verification is current."
- "Verified on" and "Valid until" for a verified ID, "Expired on" for an expired one and "Revoked on" for a revoked one. A pending ID shows no dates.
- "Requested by", the requesting business name, when one is available.
- a note that the page never shows a name, a document or a photo.

An ID that is malformed, unknown or no longer available shows the same "ID not found" screen. The page is not cached and is not for search engines.

The lookup behind the page is for browsers only. It accepts requests from the verification site's own pages and nowhere else, so a call from your server or from your own site is refused with `403 origin_not_allowed`. It also has a rate limit for each client IP address; bounds can change. To check an ID from your backend, use the session status in step 1.

### 4. Revoke or resend in Backoffice

Open Backoffice → Identity Verification → KYC Verifications, open the case, and select the Overview tab. In the "Session details" card you see "Noxtica Verification ID", "Verification ID status", "Verification ID issued", "Email on file for the ID", "Last emailed" and "Emails sent".

Administrators also see these actions. Each needs fresh step-up verification (MFA):

| Action | When it shows | Effect |
| ------ | ------------- | ------ |
| "Revoke ID" with a "Revoke reason" | An ID exists and is not revoked | The public status becomes "Revoked" immediately. The ID cannot be restored or re-issued. |
| "Resend ID email" | The customer left an address and the ID is not revoked | Backoffice emails the ID and the status link again. You never see the address. |

The revoke reasons are "Issued in error", "Fraud suspected", "Requested by the subject" and "Requested by the business". Revoking is recorded in the audit log. A session can be emailed up to 20 times in total, with at least 60 seconds between sends.

## Verify it works

1. Finish a hosted session. The status read returns `session.nvid` in the format above.
2. Open `https://verify.noxtica.com/v/<NVID>` in a browser. While the session waits for review, the page shows "Pending review" and says the verification is not verified yet.
3. After a reviewer approves the case, reload the page. It shows "Verified" with "Verified on" and "Valid until".
4. After you revoke the ID in Backoffice, reload the page. It shows "Revoked" with "Revoked on". The status read keeps returning the same `nvid` string.

## Troubleshooting

| Symptom | Cause | Fix |
| ------- | ----- | --- |
| The status read has no `nvid` key | NVIDs are not enabled for your organisation. | Ask your account team. |
| `nvid` is `null` | The session has no ID: it has not been submitted, it ended `unverified`, `error`, expired or cancelled, or it finished before NVIDs were enabled. | Read `session.status`. Create a new session if you need an ID. |
| The status page shows "ID not found" | The ID is mistyped, unknown or no longer available. | Copy the ID from the session status or the event, not from a screenshot. |
| The status page shows "Pending review" for a long time | A reviewer has not decided yet. | Open Backoffice → Identity Verification → KYC Review Queue and record a decision. |
| Your server gets `403 origin_not_allowed` | The public lookup is for browsers on the verification site. | Use the session status. |
| The page says "Too many requests. Wait a minute and try again." | The rate limit for your IP address was reached. | Wait, then retry. |
| "Resend ID email" or "Revoke ID" is missing | You lack the administrator role, no address is on file, or the ID is already revoked. | Check the role and the "Email on file for the ID" row. |
| "The ID was emailed too recently or the send limit (20) has been reached." | A send happened within 60 seconds, or the session reached 20 sends. | Wait a minute and retry, or stop at the limit. |
| "This Verification ID is already revoked." | Someone revoked it earlier. | Nothing to do. A revoke cannot be undone. |

## Related

- [Identity verification integration](https://noxtica.com/docs/identity-verification-integration/) — create sessions and read the status.
- [Identity verification events and webhooks](https://noxtica.com/docs/identity-verification-webhooks/) — the `nvid` field on `kyc.session.completed`.
- [Identity verification FAQ and troubleshooting](https://noxtica.com/docs/identity-verification-faq/) — `review_pending` and review decisions.
- [Identity verification data](https://noxtica.com/docs/identity-verification-data/) — what is kept and how an administrator deletes it.
- [Privacy](https://noxtica.com/privacy/) — how Noxtica handles personal data.

---

Source: https://noxtica.com/docs/identity-verification-business/
Markdown: https://noxtica.com/docs/identity-verification-business/index.md
Last updated: 2026-10-27

# Business and merchant verification (KYB and KYM)

KYB (know your business) and KYM (know your merchant) extend hosted verification from people to businesses and merchants. Your server creates a one-shot link, the business or merchant completes onboarding on a Noxtica page, and your operators review the case in Backoffice. A backend engineer creates the sessions, and a Backoffice administrator follows them.

## What it is

Availability: In development. Business and merchant verification is not generally open, and nothing on this page is a commitment on scope, availability or date. Whether the calls and Backoffice pages below work for your organisation depends on your organisation; ask your account team. When it is not available, Backoffice shows "KYB is not available for this workspace yet." or "Merchant verification (KYM) is not available for this workspace yet.", and the API answers `404` with `V1 endpoint not found`.

- **KYB** is hosted business onboarding. The business representative enters business information, uploads documents, declares owners, reviews and submits. A submitted session goes to human review in Backoffice. This page describes no automated business-registry check.
- **KYM** is hosted merchant onboarding plus notify-only transaction monitoring. The merchant enters a profile, uploads documents, accepts a declaration, reviews and submits. Your server can also report transactions, which feed alert rules. An alert is a notification for a person to review. It never starts a payment action.

Both hosted pages open as a full page. They cannot be embedded in an iframe. Results are signals: your operators decide, and Backoffice keeps the case and its notes.

| | KYB | KYM |
| --- | --- | --- |
| Create a session | `POST /v1/kyb/sessions` | `POST /v1/kym/sessions` |
| Key permission | Verify identity documents (KYC), scope `write:identity` | Manage KYM merchant onboarding sessions and transactions, scope `write:kym` |
| Hosted page | `https://verify.noxtica.com/b/<token>` | `https://verify.noxtica.com/m/<token>` |
| Link validity, in seconds | 3600 to 2592000, default 604800 | 3600 to 1209600, default 259200 |
| Creates | A business entity in review | A merchant case in `open` status |
| Session statuses | `pending`, `in_progress`, `submitted`, `under_review`, `completed`, `expired`, `abandoned` | `pending`, `opened`, `submitted`, `under_review`, `completed`, `expired`, `abandoned` |
| Hosted steps | business info, documents, UBO declaration, review, submit | profile, documents, declaration, review, submit |
| Backoffice | KYB: Entities, Sessions, Workflows | KYM: Cases, Sessions, Alerts, Alert Definitions |
| Events | `kyb.entity.created`, `kyb.entity.under_review`, `kyb.entity.closed` | `kym.alert.created`, `kym.case.status_changed` |

## Prerequisites

- Confirmation from your account team that KYB or KYM is enabled for your organisation. Without it, every call below answers `404`.
- A Backoffice user with the administrator role for the KYB and KYM pages. Changes ask for fresh step-up verification (MFA).
- A server key with the right permission: "Verify identity documents (KYC)" for KYB, and "Manage KYM merchant onboarding sessions and transactions" for KYM. Create it in Backoffice → API & SDK → Server API Keys. The secret is shown once. Server keys start with `sk_prod_`. Keep the key on your server.
- The hosted verification service configured for your environment. If it is not, session creation answers `503 hosted_verify_not_configured`.
- For events: an endpoint registered as in [Identity verification events and webhooks](https://noxtica.com/docs/identity-verification-webhooks/).

## Steps

### 1. Create a KYB session

```http
POST https://collect.noxtica.com/v1/kyb/sessions
Authorization: Bearer sk_prod_your_server_key
Content-Type: application/json
```

The body is a JSON object and can be `{}`. Every field is optional, and the business can fill in the real details on the hosted page. Snake_case names such as `legal_name` are accepted too.

| Field | Meaning |
| ----- | ------- |
| `legalName` | Up to 200 characters. Without it, the session starts with the placeholder "Pending business information". |
| `registrationNumber` | Up to 64 characters. |
| `countryOfIncorporation` | Two uppercase letters. Without it, the placeholder `ZZ` is used. |
| `entityKind` | `company`, `partnership`, `trust`, `foundation` or `other`. The default is `company`. |
| `expiresInSeconds` | 3600 to 2592000. The default is 604800. A value outside the range is refused, not adjusted. |

```bash
curl -sS https://collect.noxtica.com/v1/kyb/sessions \
  -H "Authorization: Bearer $NOXTICA_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"legalName":"Example Co","countryOfIncorporation":"GB","entityKind":"company"}'
```

A new session returns `200`:

```json
{
  "ok": true,
  "sessionId": "<uuid>",
  "url": "https://verify.noxtica.com/b/<token>",
  "expiresAt": 1790848845000,
  "requestId": "<request-id>"
}
```

`url` is a one-shot link that carries the access token. It is returned once, in this response, and no later call returns it. Treat it as a secret and do not log it. `expiresAt` is in epoch milliseconds.

### 2. Create a KYM session

```http
POST https://collect.noxtica.com/v1/kym/sessions
Authorization: Bearer sk_prod_your_server_key
Content-Type: application/json
```

| Field | Meaning |
| ----- | ------- |
| `merchantName` | Up to 200 characters. Without it, the session starts with the placeholder "Pending merchant information". |
| `registrationNumber` | Up to 64 characters. |
| `country` | Two letters. Lowercase is changed to uppercase. Without it, the placeholder `ZZ` is used. |
| `expiresInSeconds` | 3600 to 1209600. The default is 259200. |

The response has the same shape as the KYB response, with a `url` that starts `https://verify.noxtica.com/m/`. KYB requires an uppercase country code, and KYM accepts either case.

### 3. Send the link and follow the session in Backoffice

Send the one-shot `url` to the business representative or merchant by redirect, email or QR code, as in [Identity verification integration](https://noxtica.com/docs/identity-verification-integration/). Store the `sessionId`.

These sessions have no server-side status read like the one for identity sessions. Follow them in Backoffice (the KYB hub is at `/kyb` and the KYM hub at `/kym`), or use events:

| Backoffice page | What it does |
| --------------- | ------------ |
| KYB → KYB Entities | Review business entities, ownership graphs, documents, screening, notes and decisions. |
| KYB → KYB Sessions | Start hosted business onboarding and follow each collection session. "Onboarding session history" lists session, entity, status, step, created and expiry. |
| KYB → KYB Workflows | Publish and review the task graphs and form definitions used by KYB cases. |
| KYM → Merchant Cases | Review merchant onboarding and monitoring cases, declared parties, checks and decisions. |
| KYM → KYM Sessions | Start hosted merchant onboarding and follow each session. The history includes the case. |
| KYM → Merchant Alerts | Triage, assign and resolve notify-only transaction-monitoring alerts. |
| KYM → Alert Definitions | Create and deactivate the rules that generate merchant alerts. |

On the two sessions pages, the "Just started — one-time link" table shows a new link once, with "Copy link", "Open hosted page", "QR code" and "Live status". It is not saved anywhere. "Create test session" starts a one-hour session with no real customer data. Its name begins "TEST session ".

### 4. Report merchant transactions (KYM)

Report one observed transaction for a merchant case that already exists. Take the `caseId` from the "Case" column on KYM Sessions or from Merchant Cases.

```http
POST https://collect.noxtica.com/v1/kym/transactions
Authorization: Bearer sk_prod_your_server_key
Content-Type: application/json
```

```json
{
  "caseId": "<case-id>",
  "idempotencyKey": "txn-0001",
  "amountMinor": 1000,
  "currency": "EUR",
  "occurredAt": "2026-10-27T09:30:00Z",
  "counterpartyRef": "cp_example"
}
```

| Field | Meaning |
| ----- | ------- |
| `caseId` | Required, up to 512 characters. |
| `idempotencyKey` | Required, up to 255 characters. A repeat of the same key returns the original row. |
| `amountMinor` | Required whole number, zero or more, in the currency's minor unit. |
| `currency` | Required three-letter code. Lowercase is changed to uppercase. |
| `occurredAt` | Required timestamp that parses as a date, for example ISO 8601. |
| `counterpartyRef` | Optional reference of your own. |

A new row returns `201` with `{"ok": true, "eventId": "<id>", "deduplicated": false, "requestId": "<request-id>"}`. A repeat returns `200` with `"deduplicated": true`. The body can be at most 4096 bytes. The call only records the event for alert rules. It starts no payment.

### 5. Subscribe to events

Register an endpoint and tick the labels below under "Events to deliver" in Backoffice → Integrations & API → Webhooks. Signatures, headers and deduplication work as for identity events.

| Event | Label in Backoffice | Fires when |
| ----- | ------------------- | ---------- |
| `kyb.entity.created` | KYB entity created | An operator creates an entity in Backoffice. |
| `kyb.entity.under_review` | KYB entity under review | A hosted session is submitted, a session is started from Backoffice, or an operator moves an entity to review. |
| `kyb.entity.closed` | KYB entity closed | An operator closes the entity. |
| `kym.alert.created` | KYM alert created | A scheduled evaluation creates an alert. |
| `kym.case.status_changed` | KYM case status changed | A hosted session is submitted, or an operator changes the case status. |

The `data` objects carry no names, registration numbers or party details:

| Event family | `data` fields |
| ------------ | ------------- |
| `kyb.entity.*` | `schemaVersion`, `entityId`, `status` (`active`, `under_review`, `suspended` or `closed`, after the change), `occurredAt`, `deliveryId` |
| `kym.*` | `schemaVersion`, `caseId`, `alertId` and `severity` (for `kym.alert.created`, else `null`), `status` (`open`, `under_review`, `monitoring` or `closed`, for `kym.case.status_changed`, else `null`), `occurredAt`, `deliveryId` |

```json
{
  "id": "<deliveryId>",
  "type": "kyb.entity.under_review",
  "created_at": 1790762445000,
  "tenant_id": "<tenant-id>",
  "data": {
    "schemaVersion": "1",
    "entityId": "<entity-id>",
    "status": "under_review",
    "occurredAt": 1790762445000,
    "deliveryId": "<deliveryId>"
  }
}
```

These events are notifications, not decisions. Business and merchant events are not part of the identity delivery log, and Noxtica publishes no retry schedule for them. `kym.*` events are attempted once. Plan for a missed event: open the entity or case in Backoffice to see its current state.

## Verify it works

1. In Backoffice, open KYB → KYB Sessions (or KYM → KYM Sessions) and select "Create test session". A row appears under "Just started — one-time link". If you see "KYB is not available for this workspace yet.", the module is not enabled.
2. Select "Open hosted page", or scan the QR code, and walk through the steps.
3. Select "Live status" on the row. It shows the status and the step and refreshes by itself while the panel is open.
4. Call the create endpoint with your server key. A `200` response with `sessionId`, `url` and `expiresAt` means the module, the key and the hosted service are all in place.
5. After the session is submitted, find the entity under KYB Entities or the case under Merchant Cases.

## Troubleshooting

| Symptom | Cause | Fix |
| ------- | ----- | --- |
| `404` with `V1 endpoint not found` | The module is not enabled for your organisation, or the path is wrong. | Check the path, then ask your account team. Do not retry in a loop. |
| `404` with `case_not_found` on a transaction | No merchant case has that `caseId` in your organisation. | Copy the case id from Backoffice. |
| `403` with `API key does not have write:identity scope` (or `write:kym scope`) | The key lacks `write:identity` (KYB) or `write:kym` (KYM and transactions). | Create a key with the right permission. |
| `400` with `invalid_country` | KYB needs two uppercase letters. KYM needs two letters. | Use an ISO country code such as `GB`. |
| `400` with `invalid_ttl`, `invalid_legal_name`, `invalid_merchant_name`, `invalid_registration_number` or `invalid_entity_kind` | A field is outside the limits above. | Fix the field. A bad `expiresInSeconds` is refused. |
| `400` with `invalid_case_id`, `invalid_idempotency_key`, `invalid_amount`, `invalid_currency` or `invalid_occurred_at` | A transaction field is missing or malformed. | Fix the field. |
| `413` with `body_too_large` | The transaction body is over 4096 bytes. | Send the fields above and nothing else. |
| `415` with `invalid_request` | The content type is not JSON. | Send `Content-Type: application/json`. |
| `429` with `Rate limit exceeded` | Too many requests. | Wait for `retryAfter` or `Retry-After`. Bounds can change. |
| `503` with `hosted_verify_not_configured` | The hosted service is not set up for this environment. | Ask your account team. |
| The `url` was lost | The link is shown once. | Create a new session and let the old one expire. |

## Related

- [Identity verification events and webhooks](https://noxtica.com/docs/identity-verification-webhooks/) — register an endpoint and verify signatures.
- [Identity verification integration](https://noxtica.com/docs/identity-verification-integration/) — the same hosted-link pattern for individuals.
- [Identity verification data](https://noxtica.com/docs/identity-verification-data/) — Noxtica does not delete verification details or evidence automatically, and an administrator removes them.
- [Identity verification FAQ and troubleshooting](https://noxtica.com/docs/identity-verification-faq/) — common questions.
- [Identity verification](https://noxtica.com/products/identity-verification/) — the product overview and its limits.
- [Server API reference](https://noxtica.com/docs/api/reference/kyc/) — the generated endpoint reference.

---

Source: https://noxtica.com/docs/identity-verification-data/
Markdown: https://noxtica.com/docs/identity-verification-data/index.md
Last updated: 2026-10-27

# Verification data: storage, access and deletion

This page explains one thing: how long verification details and evidence stay in your tenant, and who can remove them. It applies to identity verification (KYC), business verification (KYB) and merchant verification (KYM) alike.

It describes the Backoffice controls and the platform's behaviour. It is not a statement of what personal data a verification captures and it is not legal advice; the [Privacy Policy](https://noxtica.com/privacy/) and the [Security page](https://noxtica.com/docs/security/) describe how Noxtica handles personal data.

## What it is

Availability: Controlled availability for identity verification; availability of business and merchant verification depends on your organisation, so ask your account team.

**Noxtica does not delete KYC, KYM or KYB verification details or evidence automatically, and it sets no retention date for them.** They stay in your tenant until a tenant administrator deletes them. Nothing expires them in the background, and no Backoffice setting schedules their removal.

Three things are easy to confuse with data expiry. None of them deletes anything:

| What expires | What it controls | What happens to the data |
| --- | --- | --- |
| A hosted link's validity (one day by default, set when the link is created) | Whether the customer can still open the link | Nothing is deleted. A session that reaches `expired` stays visible. |
| The capture window after the customer first opens the link (30 minutes) | How long the customer has to finish | Nothing is deleted. |
| A Noxtica Verification ID's validity | Whether the public status page reports the ID as valid | Nothing is deleted. See [Noxtica Verification ID (NVID)](https://noxtica.com/docs/identity-verification-id/). |

The retention schedules in Backoffice → Privacy & Legal → Data Retention govern other data, for example device events and the audit log. They do not schedule the deletion of verification details or evidence.

## Prerequisites

- **An administrator account** in your tenant. Deleting a verification, approving an erasure request, placing a legal hold, erasing a business entity or a merchant case, and reading sensitive evidence are administrator actions, and the deleting actions ask for a fresh step-up verification of the signed-in person.
- **A second administrator** for identity verification erasure requests. The person who submitted a request cannot approve it.
- **The module for the verification type provisioned** for your tenant. Without it the pages and routes below are not available.
- **A decision in your own organisation** on what you promise customers about deletion. Check with your account team what an approved erasure request covers for your tenant before you state a timeline to a customer.

## Steps

### 1. Decide who may see verification evidence

Reading the stored evidence of a verification is a separate, higher permission than reviewing a case. Backoffice → Identity Verification → Evidence Access is available to administrators only, and each read asks for a fresh step-up verification. Give that role to as few people as your process needs, and review the list under Users.

### 2. Delete identity verification data

For identity verification (KYC), a tenant administrator deletes data in two ways: delete the verifications you choose directly in Backoffice, or work a right-to-erasure request that a subject or an operator submitted.

#### Delete the verifications you choose

1. Open Backoffice → Identity Verification → KYC Verifications. Only administrators see the row checkboxes and the delete buttons.
2. To delete one verification, open its case and, on the Overview tab, select **Delete verification**. To delete several, tick the checkbox of each row on the list and select **Delete selected**. One request covers at most 25 verifications.
3. In the dialog, check the list of verifications and enter a reason of 3 to 500 characters. The reason is kept in the audit trail, so do not put personal data in it.
4. Type the confirmation phrase exactly as the dialog shows it: `delete 1 verification permanently` for one verification, `delete 3 verifications permanently` for three. The confirm button stays disabled until the phrase matches.
5. Select **Delete permanently** and complete the step-up verification when it asks.

What a delete does:

- It removes the verification and everything that belongs to it: its sessions, the evidence files and evidence records, the review decisions, the analysis signals and the webhook delivery records.
- Noxtica removes every evidence file first and confirms that each one is gone. Only then does it remove the records. If a file cannot be removed, the verification is kept and the dialog says so.
- It keeps the billing usage records, the legal-basis receipts, the opaque subject reference and the audit trail.
- It cannot be undone. Deleting a verification that is already deleted is harmless: Backoffice reports it as already deleted.
- It writes two audit entries, `kyc_verification_delete_requested` and `kyc_verification_deleted`, with your reason, who deleted it and how many records were removed from each table.
- It does not send the `kyc.erasure.completed` event. That event belongs to erasure requests.
- A legal hold in your tenant, or an open erasure request for the same subject, blocks the delete.

Deleting works only from a signed-in Backoffice session. No server API key can delete a verification.

#### Work an erasure request

1. Requests appear on the **KYC Erasure** page (Backoffice → Identity Verification → KYC Erasure, titled **KYC Erasure Requests**) after a subject or an operator submits a right-to-erasure request for your tenant. Each row shows the opaque subject reference, the status, whether a legal hold is in place, the requester, the approver and the timestamps. The page shows no raw evidence.
2. A different administrator than the requester approves the request (dual control). Approval by the same person is refused.
3. An administrator can place a legal hold on a request and release it later. While a hold is in place the request does not proceed to deletion.
4. Noxtica carries out an approved request. The **Deletion items** list on the request shows the progress of each stored item, with its receipt and the time it was deleted.
5. When a request completes, the platform sends the `kyc.erasure.completed` event to endpoints subscribed to it. The event carries the request id and the outcome only; it carries no subject identifier, and it is not sent for a request that completed only in part.

Approving, holding and releasing each ask for a fresh step-up verification. Erasure requests are keyed on the subject record that Noxtica creates for a verification, so ask your account team what a request covers for each kind of verification in your tenant before you rely on it for a customer who asks to be forgotten. To remove a specific verification yourself, delete it as described above.

There is no setting that deletes identity verification data on a schedule and no automatic expiry. A deletion is always an explicit action of a tenant administrator.

### 3. Delete a business or a merchant verification

Business (KYB) and merchant (KYM) verifications can be erased explicitly from their own pages, when the module is enabled for your organisation.

1. Open Backoffice → KYB → KYB Entities, or KYM → Merchant Cases.
2. Open the item. It must be in the closed state; an item that is still open cannot be erased.
3. Select **Erase entity** (KYB) or **Erase case** (KYM). The dialog asks for a reason of 3 to 500 characters and for a confirmation: type the legal name of the entity, or the merchant name of the case, exactly as shown.
4. Confirm and complete the step-up verification when it asks.
5. A KYB entity that another entity in your tenant still lists as a beneficial owner cannot be erased until that reference is removed.

Erasing is a hard delete. A KYB entity is removed with its uploaded documents and their stored files, notes, collection sessions, declared beneficial owners and ownership links. A KYM case is removed with its declared parties, alerts, transaction events, merchant sessions, and uploaded documents and their stored files. The audit entry keeps your reason and the number of records removed. The erased item cannot be restored.

If a stored file cannot be confirmed removed, Backoffice still reports the erase and warns you: "Erased, but N stored files could not be confirmed removed. Contact support to finish the cleanup."

### 4. Keep your own records consistent

Noxtica stores verification details for you; it does not tell your systems to forget. When you delete data in Noxtica, also remove or restrict the copies in your own systems, including the `sessionId` and `verificationId` values you stored next to your customer records and any events you logged.

## Verify it works

- A request appears under Identity Verification → KYC Erasure with its status, and moves forward after an administrator other than the requester approves it. Its Deletion items list shows each item's progress.
- A deleted verification no longer appears in KYC Verifications, its case address answers not found, and the audit log shows `kyc_verification_delete_requested` and `kyc_verification_deleted` with your reason.
- An erased KYB entity or KYM case no longer appears in its list, and the audit log shows the erase action with the reason.
- If you subscribed an endpoint to it, your handler receives `kyc.erasure.completed` for a completed erasure request with a valid signature ([Identity verification events and webhooks](https://noxtica.com/docs/identity-verification-webhooks/)).

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| The erasure page or action is missing | Your role is below administrator, or the module is not provisioned. | Sign in with an administrator account, or ask your account team. |
| The row checkboxes or **Delete verification** are missing on KYC Verifications | Your role is below administrator, or the identity verification module is not provisioned. | Sign in with an administrator account, or ask your account team. |
| **Delete permanently** stays disabled | The reason is shorter than 3 or longer than 500 characters, or the phrase does not match exactly, including the number and the singular or plural. | Enter a valid reason and type the phrase as shown. |
| "Blocked by a legal hold or an open erasure request." | A legal hold is in place in your tenant, or an erasure request for the same subject is still open. | Release the hold or let the request finish, then delete again. |
| "New evidence arrived while deleting", "The evidence store is unavailable" or "The evidence files could not be removed" | The delete did not complete. Records are removed only after every evidence file is confirmed gone, so the verification record is kept. | Try again. If it repeats, contact support. |
| "Deleting verifications is not available right now." | Verification delete is not switched on for your deployment, or the service is briefly unavailable. Nothing was changed. | Try again later, then ask your account team. |
| A request you expected is missing | Requests appear only after a subject or an operator has submitted one for your tenant. | Ask your account team how requests reach your tenant. |
| Approval is refused | The approver is the person who opened the request. | Ask a different administrator to approve. |
| The action asks for verification again | Deleting actions need a fresh step-up check. | Complete it and repeat the action. |
| **Erase entity** or **Erase case** is unavailable or refused | The item is not in the closed state, someone changed it since you opened it, or another entity still references it. | Close the item, reload and try again, and remove the reference first. |
| You expected old verifications to disappear | Nothing deletes verification data on a schedule. | Delete the verifications in KYC Verifications, open an erasure request, or erase the business or merchant item. |

## Related

- [Identity verification integration](https://noxtica.com/docs/identity-verification-integration/): hosted sessions and the link lifetimes that are not data expiry.
- [Invitations and hosted verification settings](https://noxtica.com/docs/identity-verification-invitations/): the Backoffice setup for hosted verification.
- [Identity verification events and webhooks](https://noxtica.com/docs/identity-verification-webhooks/): the `kyc.erasure.completed` event.
- [Business and merchant verification (KYB and KYM)](https://noxtica.com/docs/identity-verification-business/): the business and merchant flows.
- [Privacy Policy](https://noxtica.com/privacy/) and [Security page](https://noxtica.com/docs/security/): how Noxtica handles personal data.

---

Source: https://noxtica.com/docs/identity-verification-faq/
Markdown: https://noxtica.com/docs/identity-verification-faq/index.md
Last updated: 2026-10-27

# Identity verification FAQ and troubleshooting

This page answers the questions that backend engineers and Backoffice operators ask most about hosted identity verification. Start with the concept answers, use the five-step triage when something looks wrong, and use the troubleshooting tables to match a symptom to a fix.

## What it is

Availability: Controlled availability. Identity verification is provisioned by your account team, and optional steps apply when they are enabled for your organisation. Every answer below follows the behaviour of the hosted flow described in [Identity verification integration](https://noxtica.com/docs/identity-verification-integration/).

### Sessions and results

**What do I get back when I create a session?** A `sessionId` and a single-use `url`. Store the `sessionId`, send the customer to the `url`, then read the outcome by status read or by a signed event. See [Identity verification integration](https://noxtica.com/docs/identity-verification-integration/).

**What is the difference between `completed`, `unverified`, `error` and `review_pending`?** `completed` means a decision approved the session. `unverified` is a negative outcome. `error` means processing could not finish. `review_pending` means a person in your Backoffice must decide. It is neither an approval nor a rejection. Only `completed` is an approval.

**Why does my session wait in `review_pending`?** A finished capture currently waits for a decision in Backoffice → Identity Verification → KYC Review Queue. A session in `review_pending` does not expire while it waits. An administrator selects "Approve" or "Override", and either completes the session. "Record escalation" leaves the session as it is. There is no separate reject decision today.

**Is a result a decision about my customer?** No. A result is an automated signal. You decide what it means, and a person in your organisation should review any adverse decision before it affects a customer. Results can be wrong in either direction and are not legal proof of identity.

**Can I embed the hosted page in an iframe?** No. The page refuses to load inside a frame. Open it as a full page or in a new tab. It does not post a message to your page and does not close itself, so learn the outcome by status read or event.

**Can I set the language of the hosted page?** No. The language comes from the customer's browser, and the link accepts no parameters beyond its own path.

**How long does a link stay valid?** An unopened link stays valid for 86400 seconds by default. You can set `expiresInSeconds` from 300 to 604800. After the customer opens the link, the customer has 30 minutes to finish, or until the original expiry if that is sooner. See [KYC Hosted Sessions](https://noxtica.com/docs/kyc-hosted-sessions/).

**Can I resend, revoke or cancel a hosted link in Backoffice?** No. Backoffice has no such control for hosted links. If a link is lost or no longer wanted, create a new session and let the old one expire. Retrying with the same `Idempotency-Key` returns the same `sessionId` without the `url`.

**Do I need a return link?** No. `returnUrl` is optional. It must be an `https` address whose host you approved in Backoffice → Identity Verification → KYC Invitations → Settings. After a completed outcome the page shows a plain link to it. There is no automatic redirect, and the address carries no session id or status. Never treat a visit to your return page as proof of completion.

### Keys and events

**Which key do I use?** Create a key with the "Verify identity documents (KYC)" permission in Backoffice → API & SDK → Server API Keys. Server keys start with `sk_prod_`. Never put the key in a browser or an app.

**Should I poll the status or use events?** Use both. Events save you from polling, and the status read is the authority. When you poll, increase the delay between reads and stop at a final status.

**Which events can I receive, and do they carry my customer reference?** `kyc.session.completed`, `kyc.session.cancelled`, `kyc.verification.completed`, `kyc.erasure.completed`, `kyc.document.expiry_warning` and `kyc.reverification.due`. Some depend on settings for your organisation. Events never carry your `subjectRef`: match an event to your customer by `sessionId`. The status read returns your reference as `subjectId`. See [Identity verification events and webhooks](https://noxtica.com/docs/identity-verification-webhooks/).

**Why do I see the same event twice, or in a different order?** Delivery is at least once and order is not fixed. Deduplicate on `X-Noxtica-Delivery`, then read the status before you act.

### Data and identifiers

**What is a Noxtica Verification ID?** A short reference that a hosted session receives when it completes or waits for review. It is not a credential. See [Noxtica Verification ID](https://noxtica.com/docs/identity-verification-id/).

**What data does Noxtica keep, and can I delete it?** Noxtica does not delete verification details or evidence automatically, and it sets no retention date for them. They stay until a tenant administrator deletes them, so verification data is never deleted automatically. An administrator deletes verifications in Backoffice → Identity Verification → KYC Verifications: select **Delete verification** on a case, or tick several rows and select **Delete selected** (up to 25), give a reason, type the confirmation phrase and complete the step-up check. The delete removes the verification and its evidence files and keeps the billing usage records, the legal-basis receipts and the audit trail. Right-to-erasure requests are handled in KYC Erasure, where a request is approved by an administrator other than the requester. See [Identity verification data](https://noxtica.com/docs/identity-verification-data/), [Requests and deletion](https://noxtica.com/docs/compliance/requests-and-deletion/) and the [Privacy Policy](https://noxtica.com/privacy/).

**Are business and merchant verification available?** KYB and KYM are in development. Availability depends on your organisation; ask your account team. See [Business and merchant verification](https://noxtica.com/docs/identity-verification-business/).

## Prerequisites

- A server key with the identity permission, and access to the Backoffice KYC pages. Reading cases needs a user who can open KYC Verifications. Recording a decision needs the administrator role and fresh step-up verification (MFA).
- The `sessionId` and, when you have it, the `requestId` from the response or the error body.
- An endpoint registered under Backoffice → Integrations & API → Webhooks, if you use events.

## Steps

Triage in five steps.

### 1. Read the session status

```http
GET https://collect.noxtica.com/v1/kyc/sessions/{sessionId}
Authorization: Bearer sk_prod_your_server_key
```

A session you created always returns `200`, including an expired one. A `404` means the id is unknown, belongs to another organisation, or the module is not provisioned.

### 2. Match the status to an action

| `status` | What it means | What to do |
| -------- | ------------- | ---------- |
| `pending` | Created. The customer has not opened the link. | Wait. The link expires at `expiresAt`. |
| `opened` | The customer is working through the steps. | Wait. The session expires within 30 minutes of the customer opening the link. |
| `verifying` | The customer submitted and processing is running. | Wait and read again. If it stays longer than you expect, go to step 5. |
| `review_pending` | A decision is needed in your Backoffice. | Open KYC Review Queue and record a decision. |
| `completed` | A decision approved the session. | Continue your journey. |
| `unverified` | Processing finished with a negative outcome. | Have a person review before you act on it. |
| `error` | Processing could not finish. | Create a new session. If it repeats, go to step 5. |
| `expired` | The link or the capture window lapsed. | Create a new session. |
| `cancelled_by_user` | The customer cancelled. | Create a new session if you still need one. |

### 3. Open the case in Backoffice

Open Backoffice → Identity Verification → KYC Verifications and find the case by the `verificationId` from the status read. The case shows the checks, the decision and the timeline. For session and verification events, Backoffice → Identity Verification → KYC → KYC Processes → "View" lists the webhook deliveries for that process.

### 4. Check delivery

If you expected an event, confirm that the endpoint is enabled and subscribed to it under Integrations & API → Webhooks, that your receiver answers `2xx` within the wait per attempt (5 seconds by default), and that the signature check uses the raw body and the current secret. Read the status instead of waiting for an event that does not apply: neither `review_pending` nor `expired` sends one.

### 5. Collect the details and contact support

Quote the `requestId` from the response or error body, the `sessionId` and the time. Do not send the one-shot link, the server key or the signing secret.

## Verify it works

- Creating a session returns `200` with `sessionId`, `url`, `expiresAt` and `requestId`.
- The status read returns the status you expect, and a Backoffice case exists for a submitted session.
- Your receiver verifies each signature, drops repeated `X-Noxtica-Delivery` values and reads the status before it acts.
- Backoffice → Identity Verification → KYC → KYC Processes shows `delivered` for the events your endpoint acknowledged.

## Troubleshooting

### Creating sessions

| Symptom | Cause | Fix |
| ------- | ----- | --- |
| `404` with `V1 endpoint not found` | The module is not provisioned for your organisation, or the path is wrong. | Check the path. If it is right, ask your account team. Do not retry in a loop. |
| `401` with `invalid_api_key` | The key is missing, malformed, unknown or revoked. | Check the `Authorization` header and that the key is a current `sk_prod_` key. |
| `403` with `API key does not have write:identity scope` | The key lacks the identity permission. | Create a key with "Verify identity documents (KYC)" ticked. |
| `403` with `kyc_legal_basis_receipt_required` | Your organisation has not recorded the legal basis for hosted identity verification. | An authorised person records it in Backoffice → Identity Verification → KYC Invitations → Settings. |
| `400` with `invalid_request` or `invalid_hosted_options` | Malformed JSON, a missing or over-long `subjectRef`, an `expiresInSeconds` outside 300 to 604800, an `Idempotency-Key` outside 8 to 128 characters, or a `hostedOptions` object that is not complete. | Fix the request, and send the complete `hostedOptions` object or leave it out. An unknown field is ignored without an error, so check the spelling of each name. |
| `400` with `return_url_not_allowed` | `returnUrl` is not `https`, or its host is not approved. | Add the host in the hosted page settings, or leave `returnUrl` out. |
| A retry returned `"replayed": true` and no `url` | The `Idempotency-Key` matched an existing session. The link is shown once, in the initial response. | Create a new session with a new key and let the old one expire. |
| `429` with `Rate limit exceeded` | Too many requests. | Back off and honour `retryAfter` or `Retry-After`. Bounds can change. |
| `503` with `hosted_verify_not_configured` | The hosted service is not set up for this environment. | Ask your account team. |

### What your customer sees

| Symptom | Cause | Fix |
| ------- | ----- | --- |
| "Verification isn't ready yet" | Your hosted verification page is not fully set up. | Complete the settings and check the readiness checklist in the Backoffice KYC pages. |
| "This link has expired" | The link or the 30-minute capture window ran out. | Create a new session and send the new link. |
| The page says the browser cannot run verification | The customer opened the link in an in-app browser. | Ask the customer to open the link in their regular browser. |
| The customer cancelled and the link no longer works | A cancel ends the link. The status is `cancelled_by_user`. | Create a new session. The reason comes in the `kyc.session.cancelled` event when that event is enabled for your organisation. |

### Results and events

| Symptom | Cause | Fix |
| ------- | ----- | --- |
| A session stays in `review_pending` | Nobody has recorded a decision. | Open Backoffice → Identity Verification → KYC Review Queue and select "Approve", "Override" or "Record escalation". |
| No event arrives for `review_pending` or `expired` | Neither state sends an event. | Read the session status. |
| An event arrives minutes after the decision | Review decisions are sent on a periodic schedule. | Wait a few minutes. The status read is current. |
| The signature check fails | The body was parsed before it was hashed, the secret was rotated, or `created_at` was used instead of the timestamp header. | Hash the raw body with the current secret and the `X-Noxtica-Timestamp` header. |
| The endpoint shows "No deliveries yet" while events work | Identity event outcomes are recorded under KYC Processes, not on the endpoint row. | Open KYC Processes → "View" → "Webhook deliveries". |
| `nvid` is missing from the status read or an event | Verification IDs are not enabled for your organisation, or the session has none. | See [Noxtica Verification ID](https://noxtica.com/docs/identity-verification-id/). |

## Related

- [Identity verification integration](https://noxtica.com/docs/identity-verification-integration/) — create a session and read the outcome.
- [Identity verification events and webhooks](https://noxtica.com/docs/identity-verification-webhooks/) — register an endpoint and verify signatures.
- [Noxtica Verification ID](https://noxtica.com/docs/identity-verification-id/) — format, validity and revocation.
- [Business and merchant verification](https://noxtica.com/docs/identity-verification-business/) — KYB and KYM.
- [Identity verification data](https://noxtica.com/docs/identity-verification-data/) — what is kept and who deletes it.
- [KYC Hosted Sessions](https://noxtica.com/docs/kyc-hosted-sessions/) — expiry and the `410` responses.
- [Errors](https://noxtica.com/docs/api/errors/) — the generic error reference.

---

Source: https://noxtica.com/docs/identity-verification-operations/
Markdown: https://noxtica.com/docs/identity-verification-operations/index.md
Last updated: 2026-10-27

# Identity verification operations in Backoffice

After verifications start arriving, people in your organisation work them in the **Identity Verification** group of Backoffice. This guide covers every KYC page beyond [invitations and hosted settings](https://noxtica.com/docs/identity-verification-invitations/) and the [integration](https://noxtica.com/docs/identity-verification-integration/): what each page is for, who may use it, and what to check before you act. Reviewers and administrators do the work; a verification result is a signal, and the decision on an adverse result is yours.

## What it is

Availability: Controlled availability (identity verification). Each page below also depends on your plan, your role and the modules enabled for your organisation; a page that is not enabled says so instead of showing data.

The sidebar lists the pages under **Identity Verification**. The landing page `/kyc` is the **KYC** item; every other page is a sub-item of it. This guide describes pages and permissions. It does not list what a verification captures; see the [Privacy Policy](https://noxtica.com/privacy/) and the [Security page](https://noxtica.com/docs/security/).

| Nav label | Route | Read it | Change things | What it is for |
| --- | --- | --- | --- | --- |
| KYC | `/kyc` | Analyst | n/a | Setup status, verification steps guide, directory of KYC pages |
| KYC Verifications | `/kyc/verifications` | Analyst | Administrator + step-up | Case list, case detail, Integration tab, delete verifications |
| KYC Invitations | `/kyc/invitations` | Analyst | Administrator + step-up | Hosted links and settings: [Invitations](https://noxtica.com/docs/identity-verification-invitations/) |
| KYC Review Queue | `/kyc/review-queue` | Analyst | Administrator + step-up | Decide cases that wait for a person |
| KYC Processes (no sidebar item) | `/kyc/processes` | Analyst | Read-only | Follow one process end to end |
| KYC Erasure | `/kyc/erasure-requests` | Analyst | Administrator + step-up | Erasure requests: [Verification data](https://noxtica.com/docs/identity-verification-data/) |
| KYC Policies | `/kyc/policies` | Analyst | Administrator + step-up | Review policies, advisory screening hits, corpus versions |
| KYC Screening Cases | `/kyc/screening-cases` | Analyst | Administrator + step-up | Casework on advisory screening hits |
| KYC Rescreening | `/kyc/rescreening` | Analyst | Read-only | Rescreening coverage and hit volume |
| Assisted Recovery | `/kyc/recovery` | Administrator | Administrator + step-up | Recovery cases and appeals queue |
| Agent Delegations | `/kyc/agent-delegations` | Analyst | Revoke: Analyst + step-up. New Delegation: Administrator + step-up | Delegated agent activity (KYA × KYC) |
| Evidence Access | `/kyc/evidence` | Administrator | View, export, audit trail: Administrator + step-up | Sensitive evidence, every view audited |
| Passkeys | `/kyc/passkey-credentials` | Analyst | Administrator + step-up | Registered passkeys and authenticator trust rules |
| Step-Up Verification | `/kyc/step-up` | Analyst | Read-only | Posture of your customers' biometric step-up |
| Device Registry | `/kyc/device-registry` | Analyst | Administrator + step-up | Trusted-device links |
| Device Topology Policy | `/kyc/device-topology` | Analyst | Administrator + step-up | Active-device limits and step-up rules |

Older addresses such as `/kyc-review-queue` and `/kyc-evidence-access` redirect to these routes. The page heading can differ from the nav label: Evidence Access opens as **Sensitive Evidence Access**, Assisted Recovery as **Assisted Recovery Operations**, Passkeys as **Passkey Credentials**, Step-Up Verification as **Passkey Step-Up**.

**Step-up** is a fresh check of the signed-in person with their MFA method. Backoffice asks for it when an action needs it and then repeats the action. A completed check stays fresh for 360 minutes. It is not the same thing as the **Step-Up Verification** page, which describes your customers' step-up.

## Prerequisites

- **The identity verification module is provisioned** for your organisation. Without it the pages show "KYC verification is not enabled", or a strip reading "KYC is not included in your plan". Ask your account team.
- **Roles.** Analysts read. Administrators record decisions and change settings. See [Roles and permissions](https://noxtica.com/docs/security/roles-and-permissions/).
- **MFA enrolled** for every person who will decide or change settings, so the step-up check can complete: [Sign-in, SSO, SCIM, MFA and IP allowlist](https://noxtica.com/docs/security/sign-in-and-access/).
- **Hosted settings and a legal basis recorded** ([Invitations](https://noxtica.com/docs/identity-verification-invitations/)). Without an active legal basis for the capture surface, Backoffice refuses to approve or override.
- **Webhook endpoint (optional)** to learn about decisions: [Identity verification events and webhooks](https://noxtica.com/docs/identity-verification-webhooks/).
- **Data lifecycle.** Noxtica does not delete verification details or evidence automatically and sets no retention date. Nothing on these pages schedules a deletion. An administrator can delete verifications on purpose in KYC Verifications. See [Verification data](https://noxtica.com/docs/identity-verification-data/).

## Steps

### 1. Decide who can review and see evidence

1. Give analysts the role for reading cases, the queue, processes, screening and device pages.
2. Give administrators the role for recording decisions, running recovery and changing policies. Keep the group small: every decision is audited with the person who made it.
3. Treat **Evidence Access** as a separate, higher permission. Administrators hold the permission to open original images, video or audio, and every open asks for step-up. Review the list at Backoffice → Administration → Users.
4. Check who did what in the [audit log](https://noxtica.com/docs/security/audit-log-and-exports/).

### 2. Check setup status on the KYC overview

Open Backoffice → Identity Verification → KYC (`/kyc`).

- A confirmation line, "KYC verification is set up — invitation links will open a working verification page.", means customers can complete a link.
- A block titled "KYC verification isn't ready for this organisation" lists each missing step with a link to the page that fixes it: activate the module, configure the hosted verification page, or register the legal basis. Two steps belong to Noxtica (the module is switched off on the deployment, or hosted links cannot be issued); the list says "Contact a platform operator" for those.
- The **Verification steps** guide below it shows which capture steps are on for your organisation.
- The directory links to every KYC page and to the **Integration guide** (`/kyc/verifications?tab=integration`).

### 3. Read cases in KYC Verifications

Open Backoffice → Identity Verification → KYC Verifications (`/kyc/verifications`). The **Verifications** tab is the default; **Integration** holds the in-app integration guide.

- Search by case id, session id or subject reference. Filter by Status, Verdict, Review, Source (**Hosted** or **API**), Document type, Issuing country, Reason code and a Created date range. Switch between the List and Cards layouts and choose columns.
- Case status reads Not started, In progress, Awaiting review, Completed, Abandoned, Expired, Cancelled or Error. The count shows "1000+" when the list is capped.
- **Export** downloads the loaded rows as CSV or JSON. Names stay masked and no face images are included.
- Select a case to open `/kyc/cases/<id>`. The tabs follow the steps that ran: Overview, Document, Face & liveness, Voice, Evidence, Checks & scores, Timeline & audit, Consent. Link to a tab with `?tab=<id>`, for example `?tab=timeline`.
- Original media is sealed. **Unlock evidence** asks for step-up once, then loads items on demand and audits each one. A role without evidence access sees findings and measurements, not the originals.
- **Timeline & audit** ends with the evidence access audit: who opened which evidence object, and when.
- Showing personal details on a case is audited before it is returned. If the audit entry cannot be written, Backoffice withholds the details instead.
- **Delete verification** (on a case) and the row checkboxes with **Delete selected** (on the list, up to 25 at a time) are visible to administrators only. The dialog asks for a reason of 3 to 500 characters and a typed confirmation phrase, and the action asks for step-up. A delete removes the verification and its evidence files, keeps the billing usage records, the legal-basis receipts and the audit trail, and cannot be undone. A legal hold or an open erasure request blocks it. Steps and refusals: [Verification data](https://noxtica.com/docs/identity-verification-data/).

### 4. Work the review queue

Open Backoffice → Identity Verification → KYC Review Queue (`/kyc/review-queue`). It lists verifications that need attention: a verdict of Unverified or Failed, or the reason code **Manual review requested** (`provider_manual_review`). A finished hosted capture currently waits here. The queue filters the pages already loaded; select **Load more** to reach older rows.

1. Read the row: Subject, Verdict, Review state (Open, In review, Approved, Overridden, Closed), Reason codes and Created. Select **Open case** and read the evidence before you decide.
2. Select **Reason codes, note & history** to attach reason codes (up to 10 from the closed list) and an optional note of up to 2000 characters, and to see the timeline of the automated checks and the linked hosted session.
3. Choose one decision and confirm the dialog. **Approve** and **Override** record that you affirm or overrule the result. **Record escalation** routes the case to deeper review without affirming or overriding the result.
4. Complete the step-up check when asked. The row shows the new review state.

The same three decisions (Approve, Override, Escalate) are on the **Overview** tab of a case, with one reason code and a note.

What a decision does:

- It needs an administrator and step-up. In the queue an analyst can select the buttons but the server refuses the decision. The case page hides them and says "Recording a review requires KYC management permission and fresh MFA."
- It writes a versioned review record and an audit entry. It never changes the stored verdict of the verification.
- For a hosted session in `review_pending`, Approve or Override moves the session to `completed` and sends `kyc.session.completed` to subscribed endpoints. Escalate does not touch the session. The page has no Reject decision.
- Two people deciding at once: the second gets "This verification was reviewed in another session — reload and retry".

### 5. Follow a process end to end

Open Backoffice → Identity Verification → KYC, then **KYC Processes** in the directory (`/kyc/processes`). Each row is one customer attempt, either a **Hosted session** or an **S2S verification** (started by your server).

- Filter by status, document type, or search by session or subject id. Statuses include Awaiting review, Submitted, Verified, Unverified, Error, Expired and Cancelled by user. A recorded review decision (Approved, Overridden, In review) replaces the session status.
- Select **View** for the detail: the hosted-session timeline, the verification and decision, failures and retakes, evidence objects (kind, state and quality, never the content), the stage results and **Webhook deliveries**.
- Webhook deliveries lists each event with Event, State, Attempts and Created. It shows no signing secret and no endpoint address. Use it after a decision to confirm the event was queued and delivered, then compare with your endpoint logs.
- A process with no hosted link reads "Not hosted-originated — a tenant S2S verification." A hosted session that has not reached submit reads "Not yet admitted".

### 6. Author policies and work screening cases

Availability depends on the review-policy and advisory screening modules enabled for your organisation.

**KYC Policies** (`/kyc/policies`) has three panels.

- **Review policies.** Select **New policy** and set Priority, Action (Allow, Challenge or Block), Enabled, Shadow and a Condition as a JSON object. A new rule starts disabled and in shadow, which means it is logged and does not act. Take a rule out of shadow with **Graduate**, which asks for step-up; editing cannot do it. Graduating does not by itself make a rule challenge or block anything.
- **Response-side enforcement.** An administrator arms or disarms it for your organisation. A rule acts on a live verification when enforcement is armed, the rule is graduated and the rule resolves an acting decision; all three must hold. Disarm stops every rule at once. Ask your account team before you rely on enforcement.
- **Screening hits** and **Corpus versions.** Hits are advisory: subject, best score, matches and outcome (Clear, Potential match, Not evaluated, Evaluation error). Corpus versions show provenance of the shared screening corpus; changing the serving pin is a platform operator action.

**KYC Screening Cases** (`/kyc/screening-cases`) is casework on advisory hits. The page says it makes no enforcement decisions.

1. Open a case from the list (State, Owner, Priority, Corpus version, Updated).
2. Move it through the states: Potential match → Triaged → Investigating. From Investigating choose a disposition: **Clear as false positive**, **Confirm match**, **Mark insufficient data** or **Escalate for enhanced review**.
3. After Confirm match you can **Mark action pending** and then **Record action taken**. A case with a final disposition can be reopened.
4. Every change needs a rationale (up to 2000 characters) and step-up. **Save assignment and priority** sets the Owner ID and Low, Normal or High priority.
5. Reopening needs a different evidence reference or a newer complete corpus version.

**KYC Rescreening** (`/kyc/rescreening`) is read-only. It shows coverage by corpus version, corpus deltas and tenant hit volume. It states that per-run history is not recorded.

### 7. Run assisted recovery

Availability depends on the trusted-device registry module enabled for your organisation.

Open Backoffice → Identity Verification → Assisted Recovery (`/kyc/recovery`). Two tabs: **Recovery cases** and **Recovery appeals**. Every action asks for step-up and is audited.

1. In **Recovery cases** read Tier, Status, Readiness and the SLA badges (On track, Overdue, Escalated).
2. Use the action the case needs: **Vouch** (trusted referee), **Approve** (one of two required approvers), **Record fraud verdict**, **Block** (when the required operations lane is unavailable) or **Resolve**.
3. Resolution needs a referee vouch, or two distinct approvers plus a cleared fraud review. A different operator than the approvers must resolve.
4. In **Recovery appeals** select **Resolve** and choose Upheld, Overturned or Expired.

### 8. Manage agent delegations (KYA × KYC)

Availability depends on the agent-delegation module enabled for your organisation.

Open Backoffice → Identity Verification → Agent Delegations (`/kyc/agent-delegations`). The table shows an opaque delegation id, principal type, scope, audience, activity (Minted, Presented, Verified, Refused, Revoked), expiry and revocation state. It shows no subject identity.

- **Revoke** ends a delegation. An analyst can do it with step-up. It cannot be undone.
- **New Delegation** needs an administrator and step-up. Enter Audience and Scope as lowercase letters, digits and `:._-` (1 to 64 characters), choose the Principal type, and optionally a TTL in minutes. The server clamps the maximum.

### 9. Open sensitive evidence when a decision needs it

Availability depends on raw-evidence storage being enabled for your organisation.

Open Backoffice → Identity Verification → Evidence Access (`/kyc/evidence`), or **Unlock evidence** on a case. The list is by session and shows metadata without step-up.

1. Select a session, then **View evidence**.
2. Pick the **Access purpose** from the closed list: Identity verification, Document authenticity, Liveness check, Address verification, Manual review or Regulatory audit.
3. Complete step-up. The evidence opens in memory in the viewer; closing it clears the decrypted bytes. No public address exists for it.
4. **Download metadata manifest (CSV)** exports metadata and **Audit trail** lists the access claims and audit events for one object. Both ask for step-up.

If the audit entry for a view cannot be committed, the view is blocked. Reading evidence does not delete it: see [Verification data](https://noxtica.com/docs/identity-verification-data/).

### 10. Review passkeys, customer step-up and device trust

Availability depends on the passkey and trusted-device registry modules enabled for your organisation.

- **Passkeys** (`/kyc/passkey-credentials`) lists registered credentials with Status Active or Revoked. **Revoke** is permanent. The **AAGUID trust policy** section sets a rule per authenticator model: Decision Allow, Require attestation or Block, and Enforcement Shadow (rules are logged and do not act; the default) or Enforce. Revoking and editing rules need an administrator and step-up.
- **Step-Up Verification** (`/kyc/step-up`) is read-only: the declared step-up configuration (not the live runtime value), the count of successful step-ups and the reason-code catalog. It says no health probe exists and failed attempts leave no row.
- **Device Registry** (`/kyc/device-registry`) lists trusted-device links with Verification level and Status (Proofed (unbound), Bound, Active, Suspended, Revoked, Migrated, Tenant terminated). **Suspend** is reversible, **Revoke** is permanent. The page has no reinstate control.
- **Device Topology Policy** (`/kyc/device-topology`) sets **Maximum active devices** (1 to 100, or blank for no cap), **Shared and delegated device handling** and **Unmanaged-device handling** (Allow or Step up). Select **Save policy**. Analysts see it read-only.

## Verify it works

- The KYC overview shows the setup confirmation line, and a test invitation ([Invitations](https://noxtica.com/docs/identity-verification-invitations/)) appears in KYC Verifications and the Review Queue.
- After Approve or Override, the row shows Approved or Overridden, the case Overview shows the new version, and a hosted session leaves Awaiting review.
- Your endpoint receives `kyc.session.completed`, and the process detail lists it under **Webhook deliveries**.
- A viewed evidence object appears in the Evidence access audit of the case and in the object's **Audit trail**.
- A saved policy, topology setting or trust rule reads back after you reload the page.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| "KYC verification is not enabled", or "KYC is not included in your plan" | The module is not enabled for your organisation. | Ask your account team. |
| "Passkey module is not enabled", "Device registry is not enabled", "Agent delegation is not enabled", "Recovery operations are not enabled", "Screening cases are not enabled", "KYC rescreening is not enabled" | That page's module is not enabled. | Ask your account team. |
| The step-up dialog appears again | The completed check is older than 360 minutes. | Complete it again. Enrol MFA first if you have none. |
| Approve or Override fails with a message about the legal basis | No active legal basis covers the capture surface. | Record it under KYC Invitations → Settings. |
| "This verification was reviewed in another session — reload and retry" | Someone else recorded a decision. | Reload, read the new state and decide again if needed. |
| "This verification's review is closed and cannot be changed" | The review state is Closed. | No further decision can be recorded; read the recorded decision. |
| The queue shows "Nothing to review" | No loaded row has an Unverified or Failed verdict or a manual review reason. | Select **Load more** or check KYC Verifications. |
| "Original media is sealed" or "Evidence access required" | Step-up not done, or your role lacks evidence access. | Select **Unlock evidence**, or ask an administrator. |
| "The view was blocked because its audit event could not be committed" | Evidence views fail closed when the audit entry fails. | Try again later. |
| "A different operator must approve or resolve this recovery case." | Recovery needs separate operators. | Ask another administrator. |
| "Use Graduate to take a rule out of shadow." | A policy edit tried to switch Shadow off. | Use **Graduate**. |
| "Provide a newer indexed corpus version or a new usable evidence reference." | A screening case reopen lacks new input. | Add one of the two. |
| "Policy changed in another session. Reloaded the current policy." | Two people edited the topology policy. | Review the reloaded values and save again. |
| "Scheduled rescreening is disabled" | The scheduler that runs rescreening is switched off for this deployment. | Ask your account team. |

## Related

- [Invitations and hosted verification settings](https://noxtica.com/docs/identity-verification-invitations/): create links, set up the hosted page and the legal basis.
- [Identity verification integration](https://noxtica.com/docs/identity-verification-integration/): create sessions from your server.
- [Identity verification events and webhooks](https://noxtica.com/docs/identity-verification-webhooks/): the events a decision sends.
- [Noxtica Verification ID (NVID)](https://noxtica.com/docs/identity-verification-id/): revoke or resend an ID from a case.
- [Verification data: storage, access and deletion](https://noxtica.com/docs/identity-verification-data/): who sees evidence and how an administrator deletes data.
- [Identity verification FAQ and troubleshooting](https://noxtica.com/docs/identity-verification-faq/): session statuses and common questions.
- [Backoffice guide](https://noxtica.com/docs/backoffice/overview/): navigation, roles and shortcuts.
- [Privacy Policy](https://noxtica.com/privacy/) and [Security page](https://noxtica.com/docs/security/): how Noxtica handles personal data.

---

Source: https://noxtica.com/docs/api/webhooks/
Markdown: https://noxtica.com/docs/api/webhooks/index.md
Last updated: 2026-10-27

# API webhooks

Noxtica sends signed HTTPS requests, called deliveries, to the endpoints you register in the Backoffice under Integrations & API, Webhooks. A delivery tells your system that something happened. Treat it as a notification and read the current state from the API before you act on it.

The signing secret of an endpoint is shown once when the endpoint is created or rotated. Store it like an API key.

## Delivery request

Each delivery is a `POST` with a JSON body. These headers accompany it:

| Header | Required | Description |
| --- | --- | --- |
| `X-Noxtica-Signature` | Yes | `sha256=` followed by the lowercase hex HMAC-SHA256 of the string `<X-Noxtica-Timestamp>.<raw request body>`, keyed with the endpoint's signing secret (the secret string's UTF-8 bytes). Verify against the raw body bytes before parsing, with a constant-time comparison. |
| `X-Noxtica-Timestamp` | Yes | Unix time in milliseconds at which this attempt was signed. Every retry is re-signed with a fresh timestamp, so compare it with your own clock (a 300 second tolerance is recommended; Noxtica itself enforces none), not with the body's `created_at`. |
| `X-Noxtica-Event` | Yes | The event type; equals `type` in the body. |
| `X-Noxtica-Delivery` | Yes | The delivery id; equals `id` in the body and `data.deliveryId`. It is identical on every retry of the same delivery: use it as the deduplication key. |

Every delivery body is a JSON object with the top-level fields `id`, `type`, `created_at`, `tenant_id`, `data`. The content of `data` depends on the event and is described with each event below.

## Verify the signature

The signature header holds `sha256=` followed by the lowercase hexadecimal HMAC-SHA256 of the string `<timestamp header>.<raw request body>`, keyed with the signing secret of the endpoint. Compute it over the raw body bytes before you parse the JSON, compare it in constant time, and reject a delivery whose timestamp is outside a tolerance you choose. The samples use five minutes. The timestamp is in milliseconds since the Unix epoch.

**Node.js**

```js
import { createHmac, timingSafeEqual } from 'node:crypto';

const TOLERANCE_MS = 5 * 60 * 1000;

export function verifyWebhook({ secret, rawBody, signature, timestamp }) {
  const age = Math.abs(Date.now() - Number(timestamp));
  if (!Number.isFinite(age) || age > TOLERANCE_MS) return false;
  const expected = createHmac('sha256', secret).update(`${timestamp}.`).update(rawBody).digest('hex');
  const received = String(signature).replace(/^sha256=/, '').toLowerCase();
  const a = Buffer.from(expected);
  const b = Buffer.from(received);
  return a.length === b.length && timingSafeEqual(a, b);
}
```

**Python**

```python
import hashlib
import hmac
import time

TOLERANCE_MS = 5 * 60 * 1000

def verify_webhook(secret: str, raw_body: bytes, signature: str, timestamp: str) -> bool:
    try:
        sent = int(timestamp)
    except ValueError:
        return False
    if abs(time.time() * 1000 - sent) > TOLERANCE_MS:
        return False
    signed = timestamp.encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    received = signature.removeprefix("sha256=").lower()
    return hmac.compare_digest(expected, received)
```

**Shell (openssl)**

```bash
printf '%s.%s' "$TIMESTAMP" "$RAW_BODY" \
  | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET"
```

Compare the printed hexadecimal digest with the part of the signature header after `sha256=`.

## Delivery, retries and deduplication

Answer every delivery with a `2xx` status as soon as you have stored it, and process it afterwards. The delivery header is the same on every retry of one delivery, so use it as the deduplication key.

Noxtica sends events to the HTTPS endpoints your organisation registers in the Backoffice
(Integrations & API, Webhooks); an endpoint receives only the event types ticked on it. An
endpoint URL must be HTTPS without embedded credentials and must not point at a private,
loopback or internal address, and an organisation can register at most 25 endpoints. The
signing secret is shown once when the endpoint is created or rotated; a rotation invalidates
the old secret at once.

**Request.** Each delivery is `POST` with `Content-Type: application/json` and the headers
`X-Noxtica-Signature`, `X-Noxtica-Timestamp` (Unix **milliseconds**), `X-Noxtica-Event` and
`X-Noxtica-Delivery`. The body is the envelope `{"id","type","created_at","tenant_id","data"}`:
`id` equals `X-Noxtica-Delivery`, `created_at` is Unix milliseconds and `tenant_id` is your
organisation. Verdict payloads carry no raw IP address and no personal data.

**Signature.** `X-Noxtica-Signature` is `sha256=` plus the lowercase hex HMAC-SHA256, keyed with
the endpoint's secret (its UTF-8 bytes), of the string `<X-Noxtica-Timestamp>.<raw body>`.
Recompute it over the raw body bytes before parsing the JSON, compare in constant time, and
reject a stale timestamp (Noxtica enforces no tolerance of its own; 300 seconds is
recommended). Every retry is re-signed with a fresh timestamp.

```js
import { createHmac, timingSafeEqual } from 'node:crypto';
function verify(secret, timestamp, rawBody, signatureHeader) {
  const expected = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
  const given = signatureHeader.replace(/^sha256=/, '').toLowerCase();
  return given.length === expected.length && timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}
```

**Delivery and retries.** Delivery is at-least-once, never exactly-once: deduplicate on
`X-Noxtica-Delivery`, which is identical on every retry of the same delivery. Answer within
5 seconds; redirects are never followed. Any `2xx` marks the delivery delivered. **Any `4xx`
(including `408` and `429`) is final: it is never retried.** A `3xx`, a `5xx`, a timeout or a
network error is retried, up to 5 retries after the first attempt, after which the delivery is
recorded as dead and is not retried again. The spacing between retries is not published.
Respond `2xx` first and process asynchronously. Events can arrive out of order. A webhook is a
notification, not authority: read the resource it refers to before taking an irreversible
action. The Backoffice "Send test" button sends only a sample `submission.scored` event.

## Event catalog

| Event | Sent when | API |
| --- | --- | --- |
| [`kyc.session.completed`](https://noxtica.com/docs/api/webhooks/#kycWebhookSessionCompleted) | A hosted verification session reached a business outcome | Identity verification API |
| [`kyc.session.cancelled`](https://noxtica.com/docs/api/webhooks/#kycWebhookSessionCancelled) | The end customer cancelled a hosted verification session | Identity verification API |
| [`kyc.verification.completed`](https://noxtica.com/docs/api/webhooks/#kycWebhookVerificationCompleted) | A KYC verification request reached a terminal state | Identity verification API |
| [`kyc.erasure.completed`](https://noxtica.com/docs/api/webhooks/#kycWebhookErasureCompleted) | A KYC erasure request finished successfully | Identity verification API |
| [`kyc.document.expiry_warning`](https://noxtica.com/docs/api/webhooks/#kycWebhookDocumentExpiryWarning) | A verified identity document is approaching or past its expiry | Identity verification API |
| [`kyc.reverification.due`](https://noxtica.com/docs/api/webhooks/#kycWebhookReverificationDue) | A previously verified identity is due for re-verification | Identity verification API |
| [`submission.scored`](https://noxtica.com/docs/api/webhooks/#webhookSubmissionScored) | A submission was scored | Device intelligence API |
| [`risk.high`](https://noxtica.com/docs/api/webhooks/#webhookRiskHigh) | A submission was scored high or critical | Device intelligence API |
| [`risk.flagged`](https://noxtica.com/docs/api/webhooks/#webhookRiskFlagged) | A risk flag fired | Device intelligence API |
| [`risk.cluster_flagged`](https://noxtica.com/docs/api/webhooks/#webhookRiskClusterFlagged) | A device cluster was flagged as bad | Device intelligence API |
| [`account.agent_linked`](https://noxtica.com/docs/api/webhooks/#webhookAccountAgentLinked) | A verified agent was linked to an account for the first time | Device intelligence API |

## kyc.session.completed {#kycWebhookSessionCompleted}

A hosted verification session reached a business outcome

Sent by Noxtica to every endpoint you registered for `kyc.session.completed`
(Backoffice, Integrations & API, Webhooks). See "Webhooks (KYC)" in the API description
for the headers, the signature, retries and deduplication; they are common to all six
KYC events.

**When it fires.** A hosted session reached `completed`, `unverified` or `error`.
**It does not fire when a session lands in `review_pending`.** With the identity provider
configured today, a successful hosted capture ends in `review_pending` (the provider
routes every success to manual review, reason code `provider_manual_review`); the event
is sent later, when a Backoffice reviewer approves or overrides the case and the session
moves `review_pending` to `completed`. Allow up to about 5 minutes between the reviewer's
decision and the delivery (the relay runs on the platform's 5-minute tick). A
`review_pending` session never expires, so your system must keep waiting for the
decision (or poll `GET /v1/kyc/sessions/{sessionId}`). It never fires for `expired`
or `cancelled_by_user` sessions.

This is a notification, not authority: before you act on it, read
`GET /v1/kyc/sessions/{sessionId}`. The payload carries no subject reference; correlate
by `data.sessionId`, the id you stored when you minted the session.

### Payload

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The delivery id, `<sessionId>:<webhookId>`. Identical on every retry; equals `X-Noxtica-Delivery` and `data.deliveryId`. |
| `type` | string | Yes | Allowed values: `kyc.session.completed`. |
| `created_at` | integer (int64) | Yes | Unix ms the event occurred. |
| `tenant_id` | string | Yes |  |
| `data` | object (KycSessionCompletedWebhookData) | Yes | The `data` member of `kyc.session.completed` (`schemaVersion` `"1"`). Delivery is at-least-once: deduplicate by `deliveryId`. A webhook is a notification, not authority; read `GET /v1/kyc/sessions/{sessionId}` for the outcome. There is no subject reference, digest, evidence id or scorecard. The event does not fire when a session lands in `review_pending`; it fires when a reviewer's decision moves it to `completed`. `email` and `emailVerified` (added 2026-10-01, additive) are present only when hosted email verification is enabled for the platform AND the session has a stored address; otherwise both keys are absent. |
| `data.schemaVersion` | string | Yes | Allowed values: `1`. |
| `data.sessionId` | string (uuid) | Yes | The id the mint call returned. |
| `data.status` | string | Yes | The terminal session status. `expired` and `cancelled_by_user` sessions never emit this event. Allowed values: `completed`, `unverified`, `error`. |
| `data.verificationId` | string, nullable | Yes |  |
| `data.reasonCodes` | array of string | Yes |  |
| `data.occurredAt` | integer (int64) | Yes | Unix ms the session reached this status (its `completedAt`). |
| `data.deliveryId` | string | Yes |  |
| `data.nvid` | string | No | The session's Noxtica Verification ID (`NVID-XXXX-XXXX-XXXX-XXXX`). Present only when the session has one (the feature is enabled for your organisation and the outcome was positive); otherwise absent. Never accompanied by the address the person may have given to receive it. |
| `data.email` | string | No | Present only when the session has a stored address (and hosted email verification is enabled for the platform). The normalised address the end customer entered in the hosted flow. Unverified unless `emailVerified` is `true`. |
| `data.emailVerified` | boolean | No | Present together with `email`. `true` only if the customer clicked the confirmation link for `email`. |

### Example payload

```json
{
  "id": "6d3c3a8e-6b4b-4a8f-8f4e-0a0e6b3d9d21:wh_7f3a2c",
  "type": "kyc.session.completed",
  "created_at": 1790762445000,
  "tenant_id": "tenant_42",
  "data": {
    "schemaVersion": "1",
    "sessionId": "6d3c3a8e-6b4b-4a8f-8f4e-0a0e6b3d9d21",
    "status": "completed",
    "verificationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "reasonCodes": [],
    "occurredAt": 1790762445000,
    "deliveryId": "6d3c3a8e-6b4b-4a8f-8f4e-0a0e6b3d9d21:wh_7f3a2c"
  }
}
```

## kyc.session.cancelled {#kycWebhookSessionCancelled}

The end customer cancelled a hosted verification session

Sent when the customer confirms on the hosted page that they do not want to continue and
the session actually moves to `cancelled_by_user`. Available only when session
cancellation is enabled for your organisation. Subscriptions are opt-in per event: an
endpoint registered before this event existed does not receive it until you add it to the
endpoint's event list.

`data.cancelReason` and `data.cancelledAt` are delivered only in this event.
`GET /v1/kyc/sessions/{sessionId}` reports the terminal status `cancelled_by_user` but does
not return the cancel reason or the cancel time. An expiry emits no event; observe it by
reading the session status.

See "Webhooks (KYC)" in the API description for headers, signature, retries and
deduplication.

### Payload

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The delivery id, `<sessionId>:<webhookId>`. |
| `type` | string | Yes | Allowed values: `kyc.session.cancelled`. |
| `created_at` | integer (int64) | Yes | Unix ms the event occurred. |
| `tenant_id` | string | Yes |  |
| `data` | object (KycSessionCancelledWebhookData) | Yes | The `data` member of `kyc.session.cancelled` (`schemaVersion` `"1"`). Same delivery semantics as `KycSessionCompletedWebhookData`. `email` and `emailVerified` (added 2026-10-01, additive) are present only when hosted email verification is enabled for the platform AND the session has a stored address; otherwise both keys are absent. |
| `data.schemaVersion` | string | Yes | Allowed values: `1`. |
| `data.sessionId` | string (uuid) | Yes |  |
| `data.status` | string | Yes | Allowed values: `cancelled_by_user`. |
| `data.cancelReason` | one of KycSessionCancelReason or any, nullable | Yes |  |
| `data.cancelledAt` | integer (int64) | Yes | Unix ms. |
| `data.occurredAt` | integer (int64) | Yes | Unix ms; equal to `cancelledAt`. |
| `data.deliveryId` | string | Yes |  |
| `data.email` | string | No | Present only when the session has a stored address (and hosted email verification is enabled for the platform). The normalised address the end customer entered before cancelling. Unverified unless `emailVerified` is `true`. |
| `data.emailVerified` | boolean | No | Present together with `email`. `true` only if the customer clicked the confirmation link for `email`. |

### Example payload

```json
{
  "id": "6d3c3a8e-6b4b-4a8f-8f4e-0a0e6b3d9d21:wh_7f3a2c",
  "type": "kyc.session.cancelled",
  "created_at": 1790762300000,
  "tenant_id": "tenant_42",
  "data": {
    "schemaVersion": "1",
    "sessionId": "6d3c3a8e-6b4b-4a8f-8f4e-0a0e6b3d9d21",
    "status": "cancelled_by_user",
    "cancelReason": "not_now",
    "cancelledAt": 1790762300000,
    "occurredAt": 1790762300000,
    "deliveryId": "6d3c3a8e-6b4b-4a8f-8f4e-0a0e6b3d9d21:wh_7f3a2c"
  }
}
```

## kyc.verification.completed {#kycWebhookVerificationCompleted}

A KYC verification request reached a terminal state

Sent when a verification request (`POST /v1/kyc/verify`, or the verification a hosted
session runs when the customer submits) reaches a terminal state: `completed`,
`terminal_error`, `expired` or `cancelled`. The non-terminal states `retryable_error`
and `provider_unknown` emit nothing. `data.verdict` is the stored canonical verdict
(`verified`, `unverified` or `error`; `error` for an infrastructure-faulted terminal
request that has no verdict).

A hosted session's submit runs the same pipeline, so an endpoint subscribed to both events
can receive `kyc.verification.completed` for the same attempt as
`kyc.session.*`; with the identity provider configured today the verdict of a successful
hosted capture is `unverified` with the reason code `provider_manual_review`. Delivery
order between the two events is not guaranteed. `data.verificationId` equals
`session.verificationId` on the session status read.

See "Webhooks (KYC)" in the API description for headers, signature, retries and
deduplication.

### Payload

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The delivery id, `<verificationId>:<webhookId>`. |
| `type` | string | Yes | Allowed values: `kyc.verification.completed`. |
| `created_at` | integer (int64) | Yes | Unix ms the event occurred. |
| `tenant_id` | string | Yes |  |
| `data` | object (KycVerificationCompletedWebhookData) | Yes | The `data` member of `kyc.verification.completed` (`schemaVersion` `"1"`). A closed, non-personal field set: no subject id, digest or document value. Deduplicate by `deliveryId`; read the verification through the API before acting. |
| `data.schemaVersion` | string | Yes | Allowed values: `1`. |
| `data.verificationId` | string | Yes |  |
| `data.verdict` | string | Yes | Allowed values: `verified`, `unverified`, `error`. |
| `data.reasonCodes` | array of string | Yes | Closed reason-code catalog; may be empty. |
| `data.idType` | string | Yes | The document type asserted on the request, e.g. `passport`. |
| `data.occurredAt` | integer (int64) | Yes | Unix ms the verification reached its terminal state. |
| `data.deliveryId` | string | Yes |  |

### Example payload

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6:wh_7f3a2c",
  "type": "kyc.verification.completed",
  "created_at": 1790762440000,
  "tenant_id": "tenant_42",
  "data": {
    "schemaVersion": "1",
    "verificationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "verdict": "unverified",
    "reasonCodes": [
      "provider_manual_review"
    ],
    "idType": "passport",
    "occurredAt": 1790762440000,
    "deliveryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6:wh_7f3a2c"
  }
}
```

## kyc.erasure.completed {#kycWebhookErasureCompleted}

A KYC erasure request finished successfully

Sent when an erasure request reaches `completed`. A `partial` erasure never emits this
event. The payload deliberately carries no subject identifier or subject digest: an erasure
notification must not re-establish a link to the person whose linkage was just erased.
`data.requestId` is the erasure request's own id.

See "Webhooks (KYC)" in the API description for headers, signature, retries and
deduplication.

### Payload

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The delivery id; equals `data.deliveryId`. |
| `type` | string | Yes | Allowed values: `kyc.erasure.completed`. |
| `created_at` | integer (int64) | Yes | Unix ms the event occurred. |
| `tenant_id` | string | Yes |  |
| `data` | object (KycErasureCompletedWebhookData) | Yes | The `data` member of `kyc.erasure.completed` (`schemaVersion` `"1"`). Emitted only when the erasure request reaches `completed`; a `partial` erasure emits nothing. No subject identifier is carried. |
| `data.schemaVersion` | string | Yes | Allowed values: `1`. |
| `data.requestId` | string | Yes | The erasure request's own id; not a subject id. |
| `data.outcome` | string | Yes | Allowed values: `completed`. |
| `data.occurredAt` | integer (int64) | Yes | Unix ms the erasure request reached its terminal state. |
| `data.deliveryId` | string | Yes |  |

### Example payload

```json
{
  "id": "er_4b81d2:wh_7f3a2c",
  "type": "kyc.erasure.completed",
  "created_at": 1790900000000,
  "tenant_id": "tenant_42",
  "data": {
    "schemaVersion": "1",
    "requestId": "er_4b81d2",
    "outcome": "completed",
    "occurredAt": 1790900000000,
    "deliveryId": "er_4b81d2:wh_7f3a2c"
  }
}
```

## kyc.document.expiry_warning {#kycWebhookDocumentExpiryWarning}

A verified identity document is approaching or past its expiry

Sent by the scheduled document-expiry monitoring pass when a monitored verification's
document crosses the 90, 60 or 30 day threshold or has expired (`data.alertType`). Only
available when document-expiry monitoring is enabled for your organisation. Each
threshold fires once per monitored verification.

Unlike the other KYC events, this event is not read from the delivery ledger: the
scheduled pass makes a single signed delivery attempt to each subscribed endpoint and
does not retry a failed attempt. Deduplicate on the delivery id anyway, and use
`data.verificationId` to correlate with the original `kyc.verification.completed`.
See "Webhooks (KYC)" for headers and signature.

### Payload

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The delivery id; equals `data.deliveryId`. |
| `type` | string | Yes | Allowed values: `kyc.document.expiry_warning`. |
| `created_at` | integer (int64) | Yes | Unix ms the event occurred. |
| `tenant_id` | string | Yes |  |
| `data` | object (KycDocumentExpiryWarningWebhookData) | Yes | The `data` member of `kyc.document.expiry_warning` (`schemaVersion` `"1"`). No subject id and no document number: correlate by `verificationId`. |
| `data.schemaVersion` | string | Yes | Allowed values: `1`. |
| `data.verificationId` | string | Yes |  |
| `data.alertType` | string | Yes | Allowed values: `expiry_90d`, `expiry_60d`, `expiry_30d`, `expiry_expired`. |
| `data.documentExpiresAt` | integer (int64) | Yes | Unix ms the monitored document expires (or expired). |
| `data.occurredAt` | integer (int64) | Yes | Unix ms the threshold crossing was detected. |
| `data.deliveryId` | string | Yes |  |

### Example payload

```json
{
  "id": "sched_91c0:wh_7f3a2c",
  "type": "kyc.document.expiry_warning",
  "created_at": 1798538000000,
  "tenant_id": "tenant_42",
  "data": {
    "schemaVersion": "1",
    "verificationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "alertType": "expiry_30d",
    "documentExpiresAt": 1801130000000,
    "occurredAt": 1798538000000,
    "deliveryId": "sched_91c0:wh_7f3a2c"
  }
}
```

## kyc.reverification.due {#kycWebhookReverificationDue}

A previously verified identity is due for re-verification

Sent by the same scheduled monitoring pass as `kyc.document.expiry_warning` when a
re-verification schedule entry reaches its due time. Only available when document-expiry
monitoring is enabled for your organisation, and only for a verification that has a
re-verification schedule entry. Single signed delivery attempt, no retry, as for
`kyc.document.expiry_warning`.

See "Webhooks (KYC)" in the API description for headers and signature.

### Payload

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The delivery id; equals `data.deliveryId`. |
| `type` | string | Yes | Allowed values: `kyc.reverification.due`. |
| `created_at` | integer (int64) | Yes | Unix ms the event occurred. |
| `tenant_id` | string | Yes |  |
| `data` | object (KycReverificationDueWebhookData) | Yes | The `data` member of `kyc.reverification.due` (`schemaVersion` `"1"`). No subject id. |
| `data.schemaVersion` | string | Yes | Allowed values: `1`. |
| `data.verificationId` | string | Yes |  |
| `data.dueAt` | integer (int64) | Yes | Unix ms the re-verification became due. |
| `data.occurredAt` | integer (int64) | Yes |  |
| `data.deliveryId` | string | Yes |  |

### Example payload

```json
{
  "id": "sched_92d1:wh_7f3a2c",
  "type": "kyc.reverification.due",
  "created_at": 1801130000000,
  "tenant_id": "tenant_42",
  "data": {
    "schemaVersion": "1",
    "verificationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "dueAt": 1801130000000,
    "occurredAt": 1801130000000,
    "deliveryId": "sched_92d1:wh_7f3a2c"
  }
}
```

## submission.scored {#webhookSubmissionScored}

A submission was scored

Sent for every scored browser or app submission of your organisation (the broadest
subscription: use `risk.high` or `risk.flagged` if you only need the notable ones). The
Backoffice "Send test" button sends a sample of this event type, with placeholder verdict
data and a valid signature.

`data.event_id` is the request id of the submission: correlate it with the `X-Request-Id`
your browser integration received. `data.device_id` is the opaque device id
(`fingerprintId`). This is a notification, not authority; read the device
(`GET /v1/device/{deviceId}`) before taking an irreversible action.

See "Webhook delivery and retries" in the API description for the headers, the signature,
retries and deduplication.

### Payload

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The delivery id; equals `X-Noxtica-Delivery`. |
| `type` | string | Yes | Allowed values: `submission.scored`, `risk.high`, `risk.flagged`, `risk.cluster_flagged`. |
| `created_at` | integer (int64) | Yes | Unix ms the event was produced. |
| `tenant_id` | string | Yes |  |
| `data` | object (VerdictWebhookData) | Yes | The verdict of one scored submission. Never carries a raw IP address or personal data. |
| `data.score` | number | No | The numeric risk score. |
| `data.risk_level` | string | No | The verdict band, for example `low`, `medium`, `high` or `critical`. |
| `data.confidence` | number | No | Model confidence from 0 to 1. |
| `data.flags` | array of string | No | The risk flags that fired. |
| `data.reason_codes` | array of string | No | The published reason-code projection of `flags`; empty unless reason-code output is enabled for your organisation. |
| `data.device_id` | string | Yes | The opaque device id. An empty string means that no stable per-device identity is available for this event. |
| `data.domain_id` | string | Yes | Your domain id. |
| `data.event_id` | string | Yes | The request id of the submission or attestation; always present. |

### Example payload

```json
{
  "id": "6d3c3a8e-6b4b-4a8f-8f4e-0a0e6b3d9d21",
  "type": "submission.scored",
  "created_at": 1790762445000,
  "tenant_id": "YOUR_TENANT_ID",
  "data": {
    "score": 12,
    "risk_level": "low",
    "confidence": 0.91,
    "flags": [],
    "reason_codes": [],
    "device_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
    "domain_id": "dom_42",
    "event_id": "8f1c2a52-6a6e-4b0e-9d52-2a7c1d9e4b10"
  }
}
```

## risk.high {#webhookRiskHigh}

A submission was scored high or critical

Sent when a scored submission lands in the `high` or `critical` risk band. The payload is
the same verdict shape as `submission.scored`. A submission in that band also produces
`submission.scored` (and `risk.flagged` when a flag fired) for endpoints subscribed to
those types.

See "Webhook delivery and retries" in the API description for the headers, the signature,
retries and deduplication.

### Payload

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The delivery id; equals `X-Noxtica-Delivery`. |
| `type` | string | Yes | Allowed values: `submission.scored`, `risk.high`, `risk.flagged`, `risk.cluster_flagged`. |
| `created_at` | integer (int64) | Yes | Unix ms the event was produced. |
| `tenant_id` | string | Yes |  |
| `data` | object (VerdictWebhookData) | Yes | The verdict of one scored submission. Never carries a raw IP address or personal data. |
| `data.score` | number | No | The numeric risk score. |
| `data.risk_level` | string | No | The verdict band, for example `low`, `medium`, `high` or `critical`. |
| `data.confidence` | number | No | Model confidence from 0 to 1. |
| `data.flags` | array of string | No | The risk flags that fired. |
| `data.reason_codes` | array of string | No | The published reason-code projection of `flags`; empty unless reason-code output is enabled for your organisation. |
| `data.device_id` | string | Yes | The opaque device id. An empty string means that no stable per-device identity is available for this event. |
| `data.domain_id` | string | Yes | Your domain id. |
| `data.event_id` | string | Yes | The request id of the submission or attestation; always present. |

### Example payload

```json
{
  "id": "0b9d7b1c-2f0e-4c8b-9a52-7c1b3a1f9e11",
  "type": "risk.high",
  "created_at": 1790762446000,
  "tenant_id": "YOUR_TENANT_ID",
  "data": {
    "score": 87,
    "risk_level": "high",
    "confidence": 0.88,
    "flags": [
      "example_flag"
    ],
    "reason_codes": [],
    "device_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
    "domain_id": "dom_42",
    "event_id": "3a7d1e52-6a6e-4b0e-9d52-2a7c1d9e4b11"
  }
}
```

## risk.flagged {#webhookRiskFlagged}

A risk flag fired

Sent when at least one risk flag fired on a scored submission, whatever its risk band.

The same event type is also sent after each mobile attestation `verify` (see
`POST /v1/attest/android` and `POST /v1/attest/ios`), with `flags` of the form
`mobile_attest:<platform>`, `mobile_attest_level:<level>` and `mobile_attest_verdict:<verdict>`.
There `data.device_id` can be an empty string, which means that no stable per-device
identity is available for the event: do not group events on an empty `device_id`, and use
`data.event_id`, which is always present, as the per-event key.

See "Webhook delivery and retries" in the API description for the headers, the signature,
retries and deduplication.

### Payload

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The delivery id; equals `X-Noxtica-Delivery`. |
| `type` | string | Yes | Allowed values: `submission.scored`, `risk.high`, `risk.flagged`, `risk.cluster_flagged`. |
| `created_at` | integer (int64) | Yes | Unix ms the event was produced. |
| `tenant_id` | string | Yes |  |
| `data` | object (VerdictWebhookData) | Yes | The verdict of one scored submission. Never carries a raw IP address or personal data. |
| `data.score` | number | No | The numeric risk score. |
| `data.risk_level` | string | No | The verdict band, for example `low`, `medium`, `high` or `critical`. |
| `data.confidence` | number | No | Model confidence from 0 to 1. |
| `data.flags` | array of string | No | The risk flags that fired. |
| `data.reason_codes` | array of string | No | The published reason-code projection of `flags`; empty unless reason-code output is enabled for your organisation. |
| `data.device_id` | string | Yes | The opaque device id. An empty string means that no stable per-device identity is available for this event. |
| `data.domain_id` | string | Yes | Your domain id. |
| `data.event_id` | string | Yes | The request id of the submission or attestation; always present. |

### Example payload

```json
{
  "id": "9c1e5d2a-3b4f-4a6c-8d7e-1f2a3b4c5d6e",
  "type": "risk.flagged",
  "created_at": 1790762447000,
  "tenant_id": "YOUR_TENANT_ID",
  "data": {
    "score": 40,
    "risk_level": "medium",
    "confidence": 0.7,
    "flags": [
      "example_flag"
    ],
    "reason_codes": [],
    "device_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
    "domain_id": "dom_42",
    "event_id": "5e8f2a52-6a6e-4b0e-9d52-2a7c1d9e4b12"
  }
}
```

## risk.cluster_flagged {#webhookRiskClusterFlagged}

A device cluster was flagged as bad

Sent once, on the first escalation, when a cluster of devices (devices sharing an
observational sub-fingerprint) is flagged bad in real time because a high or critical
submission came with strong cluster evidence. It lets you react to an emerging cluster
before slower offline feeds catch up. A cluster that is already flagged does not produce
a new delivery for every further submission.

The payload has the same verdict shape as `submission.scored`; `data.risk_level` is the
cluster's band. It carries no raw IP address and no personal data. Available only when
real-time cluster propagation is enabled for the deployment.

See "Webhook delivery and retries" in the API description for the headers, the signature,
retries and deduplication.

### Payload

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The delivery id; equals `X-Noxtica-Delivery`. |
| `type` | string | Yes | Allowed values: `submission.scored`, `risk.high`, `risk.flagged`, `risk.cluster_flagged`. |
| `created_at` | integer (int64) | Yes | Unix ms the event was produced. |
| `tenant_id` | string | Yes |  |
| `data` | object (VerdictWebhookData) | Yes | The verdict of one scored submission. Never carries a raw IP address or personal data. |
| `data.score` | number | No | The numeric risk score. |
| `data.risk_level` | string | No | The verdict band, for example `low`, `medium`, `high` or `critical`. |
| `data.confidence` | number | No | Model confidence from 0 to 1. |
| `data.flags` | array of string | No | The risk flags that fired. |
| `data.reason_codes` | array of string | No | The published reason-code projection of `flags`; empty unless reason-code output is enabled for your organisation. |
| `data.device_id` | string | Yes | The opaque device id. An empty string means that no stable per-device identity is available for this event. |
| `data.domain_id` | string | Yes | Your domain id. |
| `data.event_id` | string | Yes | The request id of the submission or attestation; always present. |

### Example payload

```json
{
  "id": "2a4c6e8f-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
  "type": "risk.cluster_flagged",
  "created_at": 1790762448000,
  "tenant_id": "YOUR_TENANT_ID",
  "data": {
    "score": 91,
    "risk_level": "critical",
    "confidence": 0.93,
    "flags": [
      "example_flag"
    ],
    "reason_codes": [],
    "device_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
    "domain_id": "dom_42",
    "event_id": "7a9b1c52-6a6e-4b0e-9d52-2a7c1d9e4b13"
  }
}
```

## account.agent_linked {#webhookAccountAgentLinked}

A verified agent was linked to an account for the first time

Sent once, when a cryptographically verified signed agent (Web Bot Auth, RFC 9421) is linked
to one of your end-user accounts for the first time, that is when the (agent, account)
pair had no earlier link. It lets you react when a new agent starts acting on an account.

The payload carries the keyed `account_hash` (a 16-character lowercase-hex pseudonym; the
raw account id is never stored or sent), the verified agent's `agent_keyid` and
`agent_host`, and the usual `device_id`, `domain_id` and `event_id`. It carries no raw IP
address and no personal data. Use `GET /v1/accounts/{accountHash}/devices` to list the
devices and agents linked to the account.

See "Webhook delivery and retries" in the API description for the headers, the signature,
retries and deduplication.

### Payload

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The delivery id; equals `X-Noxtica-Delivery`. |
| `type` | string | Yes | Allowed values: `account.agent_linked`. |
| `created_at` | integer (int64) | Yes | Unix ms the event was produced. |
| `tenant_id` | string | Yes |  |
| `data` | object (AgentLinkedWebhookData) | Yes | The first link between a verified agent and one of your accounts. Never carries a raw account id, IP address or personal data. |
| `data.account_hash` | string | Yes | The keyed 16-character lowercase-hex account pseudonym. |
| `data.agent_keyid` | string | Yes | The verified agent's `Signature-Input` key id. |
| `data.agent_host` | string, nullable | Yes | The verified agent's directory host |
| `data.device_id` | string | Yes |  |
| `data.domain_id` | string | Yes |  |
| `data.event_id` | string | Yes |  |

### Example payload

```json
{
  "id": "4d6f8a1c-5e7b-4d9f-8a2c-3b5d7f9a1c2e",
  "type": "account.agent_linked",
  "created_at": 1790762449000,
  "tenant_id": "YOUR_TENANT_ID",
  "data": {
    "account_hash": "0a1b2c3d4e5f6071",
    "agent_keyid": "agent-key-1",
    "agent_host": "agent.example.com",
    "device_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
    "domain_id": "dom_42",
    "event_id": "9b1d3f52-6a6e-4b0e-9d52-2a7c1d9e4b14"
  }
}
```

_This page is generated from the Noxtica OpenAPI specification release `v0.4.0`: `kyc.yaml` version `1.2.0-2026-10-27` (SHA-256 `c91a695cfde0`), `mcp.yaml` version `0.1.0-2026-10-27` (SHA-256 `1a4875efa736`), `pulse.yaml` version `0.9.0-2026-10-27` (SHA-256 `95196a58bb5b`), `v1.yaml` version `1.3.0-2026-10-27` (SHA-256 `3fd15257a022`). Do not edit it by hand._

---

Source: https://noxtica.com/docs/identity-verification-webhooks/
Markdown: https://noxtica.com/docs/identity-verification-webhooks/index.md
Last updated: 2026-10-27

# Identity verification events and webhooks

Identity verification sends signed HTTPS events to endpoints you register in Backoffice, so your server does not have to poll for outcomes. A Backoffice administrator registers the endpoint. A backend engineer verifies each delivery, removes duplicates and reads the session status before acting.

## What it is

Availability: Controlled availability. Events belong to identity verification, which your account team provisions for your organisation. Events marked "when enabled for your organisation" depend on settings your account team controls.

An event is a notification, not a decision. Each delivery is a `POST` with a JSON envelope and four headers, signed with the signing secret of the endpoint that receives it. The six identity events are:

| Event | Fires when | Delivery |
| ----- | ---------- | -------- |
| `kyc.session.completed` | A hosted session reaches `completed`, `unverified` or `error`. A session in `review_pending` fires it later, when a reviewer approves or overrides the case. | Retried |
| `kyc.session.cancelled` | The customer cancels on the hosted page. Subscribe to it explicitly. When enabled for your organisation. | Retried |
| `kyc.verification.completed` | A verification reaches a final state, whether it came from a hosted session or from a direct API call. | Retried |
| `kyc.erasure.completed` | An erasure request reaches `completed`. A `partial` erasure sends nothing. When erasure is enabled for your organisation. | Retried |
| `kyc.document.expiry_warning` | A verified document is 90, 60 or 30 days from expiry, or has expired. When enabled for your organisation. | Single attempt |
| `kyc.reverification.due` | A scheduled re-verification becomes due. When enabled for your organisation. | Single attempt |

"Retried" means up to 5 more attempts (step 5). "Single attempt" means one try with no retry. A session that expires sends no event. Read its status to see `expired`. Events for business and merchant verification (`kyb.entity.*`, `kym.*`) are on [Business and merchant verification](https://noxtica.com/docs/identity-verification-business/). The generic envelope and header reference is on [Webhooks](https://noxtica.com/docs/api/webhooks/).

## Prerequisites

- Identity verification provisioned for your organisation. See [Identity verification integration](https://noxtica.com/docs/identity-verification-integration/).
- A Backoffice user with the administrator role. The Webhooks page is restricted to administrators, and every change asks for fresh step-up verification (MFA).
- A public HTTPS endpoint. Localhost, private addresses, internal names and URLs that carry a user name or password are refused. A custom HTTPS port is allowed.
- Room for the endpoint: an organisation can register up to 25 endpoints, and each URL can be registered once.
- A server-side secret store for the signing secret. The secret is shown once.
- An endpoint that answers within 5 seconds. That is the default wait for each attempt; bounds can change.

## Steps

### 1. Register the endpoint

1. Open Backoffice → Integrations & API → Webhooks (`/integrations/webhooks`). Stay on the "Manage" tab. The "Integration" tab holds the in-product guide.
2. Under "Add endpoint", enter the "Endpoint URL". Add a "Description (optional)" of up to 200 characters if you want one.
3. Under "Events to deliver", tick the identity events you need. Select at least one event.
4. Select "Add endpoint" and complete the step-up prompt.
5. Copy the secret from "Copy your signing secret now" into your server secret store, then select "I've copied it". Backoffice never shows it again.

The Backoffice label for each identity event:

| Event | Label in "Events to deliver" |
| ----- | ---------------------------- |
| `kyc.session.completed` | Hosted KYC session completed |
| `kyc.session.cancelled` | Hosted KYC session cancelled by the end user |
| `kyc.verification.completed` | KYC verification completed |
| `kyc.erasure.completed` | KYC erasure completed |
| `kyc.document.expiry_warning` | KYC document expiry warning |
| `kyc.reverification.due` | KYC re-verification due |

Subscriptions are per event. An endpoint receives the events you ticked, and an event type added to the platform later is not added to an existing endpoint.

### 2. Receive and acknowledge deliveries

Every delivery is an HTTPS `POST` with `Content-Type: application/json` and these headers:

| Header | Value |
| ------ | ----- |
| `X-Noxtica-Signature` | `sha256=` followed by the lowercase hex HMAC-SHA256 signature |
| `X-Noxtica-Timestamp` | The time of this attempt in epoch milliseconds. It changes on every retry. |
| `X-Noxtica-Event` | The event type, equal to `type` in the body |
| `X-Noxtica-Delivery` | The delivery id, equal to `id` in the body and to `data.deliveryId`. It stays the same across retries. |

The body is one envelope:

| Field | Meaning |
| ----- | ------- |
| `id` | The delivery id. Treat it as an opaque string. |
| `type` | The event type. |
| `created_at` | When the event occurred, in epoch milliseconds. It equals `data.occurredAt`. |
| `tenant_id` | Your organisation id. |
| `data` | The event fields in step 4. `schemaVersion` (`"1"`) sits inside `data`, not on the envelope. |

Answer with a `2xx` status and do the work afterwards. Noxtica does not follow redirect responses.

### 3. Verify the signature

The signature is an HMAC-SHA256 over `<timestamp>.<raw body>`, keyed with the endpoint's signing secret as UTF-8 text. Verify it before you parse or trust anything in the body.

- Use the body exactly as received. Do not parse and re-serialise it.
- Compare in constant time.
- Check the timestamp header, not `created_at`. Every retry is signed again with a fresh timestamp.
- Noxtica enforces no timestamp window. Enforce your own; five minutes is a sensible tolerance.

```js
import { createHmac, timingSafeEqual } from 'node:crypto';

const TOLERANCE_MS = 5 * 60 * 1000;

export function verifyNoxticaWebhook({ secret, timestamp, signature, rawBody, now = Date.now() }) {
  const sentAt = Number(timestamp);
  if (!Number.isSafeInteger(sentAt) || Math.abs(now - sentAt) > TOLERANCE_MS) return false;

  const expected = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
  const provided = String(signature).replace(/^sha256=/, '').toLowerCase();

  const expectedBytes = Buffer.from(expected);
  const providedBytes = Buffer.from(provided);
  return expectedBytes.length === providedBytes.length && timingSafeEqual(expectedBytes, providedBytes);
}
```

Save the verifier above as `verify-noxtica-webhook.mjs`. This receiver keeps the raw body, deduplicates and acknowledges quickly:

```js
import { createServer } from 'node:http';
import { verifyNoxticaWebhook } from './verify-noxtica-webhook.mjs';

const seen = new Set(); // replace with a durable store shared by all your instances

createServer(async (req, res) => {
  const chunks = [];
  for await (const chunk of req) chunks.push(chunk);
  const rawBody = Buffer.concat(chunks).toString('utf8');

  const valid = verifyNoxticaWebhook({
    secret: process.env.NOXTICA_WEBHOOK_SECRET,
    timestamp: req.headers['x-noxtica-timestamp'],
    signature: req.headers['x-noxtica-signature'],
    rawBody,
  });
  if (!valid) return res.writeHead(401).end();

  const deliveryId = req.headers['x-noxtica-delivery'];
  if (!seen.has(deliveryId)) {
    seen.add(deliveryId);
    void handleEvent(JSON.parse(rawBody)); // step 5
  }
  res.writeHead(204).end();
}).listen(3000);
```

The same check in Python:

```python
import hashlib
import hmac
import time

TOLERANCE_MS = 5 * 60 * 1000

def verify_noxtica_webhook(secret: str, timestamp: str, signature: str, raw_body: bytes) -> bool:
    if not (timestamp.isascii() and timestamp.isdigit()):
        return False
    if abs(time.time() * 1000 - int(timestamp)) > TOLERANCE_MS:
        return False

    signed = timestamp.encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    provided = signature.removeprefix("sha256=").lower()
    return hmac.compare_digest(expected, provided)
```

### 4. Handle each event

Every identity `data` object carries `schemaVersion` (`"1"`), `occurredAt` (epoch milliseconds) and `deliveryId`. No identity event carries your `subjectRef`, a name or a document value. `reasonCodes` come from a closed catalog; see [Server API reference](https://noxtica.com/docs/api/reference/kyc/). Ignore fields you do not recognise.

#### `kyc.session.completed`

The delivery id is `<sessionId>:<webhookId>`.

| Field | Meaning |
| ----- | ------- |
| `sessionId` | The `sessionId` you stored when you created the session. |
| `status` | `completed`, `unverified` or `error`. |
| `verificationId` | The verification case id, or `null` when no verification ran. |
| `reasonCodes` | An array of closed reason codes. It can be empty. |
| `nvid` | Optional. The Noxtica Verification ID, when one was issued. See [Noxtica Verification ID](https://noxtica.com/docs/identity-verification-id/). |
| `email`, `emailVerified` | Optional. The address the customer entered and whether they confirmed it. Present when email verification is enabled for your organisation and an address was entered. It is personal data. |

```json
{
  "id": "<sessionId>:<webhookId>",
  "type": "kyc.session.completed",
  "created_at": 1790762445000,
  "tenant_id": "<tenant-id>",
  "data": {
    "schemaVersion": "1",
    "sessionId": "<sessionId>",
    "status": "completed",
    "verificationId": "<verification-id>",
    "reasonCodes": [],
    "occurredAt": 1790762445000,
    "deliveryId": "<sessionId>:<webhookId>"
  }
}
```

A finished capture currently waits in `review_pending`. This event follows when a reviewer approves or overrides the case in Backoffice, normally within a few minutes of the decision.

#### `kyc.session.cancelled`

The delivery id is `<sessionId>:<webhookId>`. It fires once, when the customer's cancel moves the session to `cancelled_by_user`. A repeated cancel, a refused cancel and an expiry send nothing. Persist the reason from the event: the status read does not return it.

| Field | Meaning |
| ----- | ------- |
| `sessionId` | The session id. |
| `status` | Always `cancelled_by_user`. |
| `cancelReason` | `not_now`, `privacy_concern`, `no_document`, `technical_problem`, `other`, or `null`. |
| `cancelledAt` | When the customer cancelled, in epoch milliseconds. |
| `email`, `emailVerified` | Optional, as above. |

```json
{
  "id": "<sessionId>:<webhookId>",
  "type": "kyc.session.cancelled",
  "created_at": 1790762300000,
  "tenant_id": "<tenant-id>",
  "data": {
    "schemaVersion": "1",
    "sessionId": "<sessionId>",
    "status": "cancelled_by_user",
    "cancelReason": "not_now",
    "cancelledAt": 1790762300000,
    "occurredAt": 1790762300000,
    "deliveryId": "<sessionId>:<webhookId>"
  }
}
```

#### `kyc.verification.completed`

The delivery id is `<verificationId>:<webhookId>`. A hosted session runs a verification too, so an endpoint subscribed to both events can receive this one and `kyc.session.completed` for the same session. Correlate by `verificationId`. The order between the two is not fixed.

| Field | Meaning |
| ----- | ------- |
| `verificationId` | The verification id. It equals `session.verificationId` on the status read. |
| `verdict` | `verified`, `unverified` or `error`. |
| `reasonCodes` | An array of closed reason codes. It can be empty. |
| `idType` | The document type asserted on the request. |

```json
{
  "id": "<verificationId>:<webhookId>",
  "type": "kyc.verification.completed",
  "created_at": 1790762440000,
  "tenant_id": "<tenant-id>",
  "data": {
    "schemaVersion": "1",
    "verificationId": "<verificationId>",
    "verdict": "unverified",
    "reasonCodes": ["<reason-code>"],
    "idType": "passport",
    "occurredAt": 1790762440000,
    "deliveryId": "<verificationId>:<webhookId>"
  }
}
```

#### `kyc.erasure.completed`

It fires when an erasure request reaches `completed`. It deliberately carries no subject identifier, so the notice cannot re-link to the person. Noxtica does not delete verification details or evidence automatically. An administrator deletes verifications in Backoffice → Identity Verification → KYC Verifications, which does not send this event, or works an erasure request in KYC Erasure, where a request is approved by an administrator other than the requester. See [Identity verification data](https://noxtica.com/docs/identity-verification-data/).

| Field | Meaning |
| ----- | ------- |
| `requestId` | The id of the erasure request. It is not a subject id. |
| `outcome` | Always `completed`. |

```json
{
  "id": "<deliveryId>",
  "type": "kyc.erasure.completed",
  "created_at": 1790900000000,
  "tenant_id": "<tenant-id>",
  "data": {
    "schemaVersion": "1",
    "requestId": "<erasure-request-id>",
    "outcome": "completed",
    "occurredAt": 1790900000000,
    "deliveryId": "<deliveryId>"
  }
}
```

#### `kyc.document.expiry_warning` and `kyc.reverification.due`

A scheduled job sends both, when enabled for your organisation. The delivery id is `<scheduleRowId>:<webhookId>`. Match `verificationId` to the original verification. Each threshold fires once and is attempted once, so a failed attempt is not retried. Reconcile from your own records if you miss one.

| Field | Event | Meaning |
| ----- | ----- | ------- |
| `verificationId` | both | The verification whose document is expiring, or that is due again. |
| `alertType` | expiry | `expiry_90d`, `expiry_60d`, `expiry_30d` or `expiry_expired`. |
| `documentExpiresAt` | expiry | When the document expires or expired, in epoch milliseconds. |
| `dueAt` | re-verification | When the re-verification became due, in epoch milliseconds. |

```json
{
  "id": "<scheduleRowId>:<webhookId>",
  "type": "kyc.document.expiry_warning",
  "created_at": 1798538000000,
  "tenant_id": "<tenant-id>",
  "data": {
    "schemaVersion": "1",
    "verificationId": "<verificationId>",
    "alertType": "expiry_30d",
    "documentExpiresAt": 1801130000000,
    "occurredAt": 1798538000000,
    "deliveryId": "<scheduleRowId>:<webhookId>"
  }
}
```

### 5. Deduplicate, tolerate order and read the status

Delivery is at least once. Noxtica answers each outcome as follows:

| Your response | What happens |
| ------------- | ------------ |
| `2xx` | Delivered. |
| `4xx`, including `408` and `429` | Final. Not retried. Return a `4xx` when you mean it. |
| `3xx`, `5xx`, a timeout or a network error | Retried, up to 5 more attempts. The spacing is not published. |
| All retries fail | Marked `dead`. The endpoint stays enabled and Noxtica does not send the delivery again. |
| The URL is no longer a public HTTPS target | Refused and not retried. |

- Deduplicate on `X-Noxtica-Delivery`. Record it before you act.
- Do not rely on order. Two events for the same session can arrive in either order.
- There is no redelivery button and no replay API. To catch up, read the state: for hosted sessions, call the status read, and for a verification, open it in Backoffice → Identity Verification → KYC Verifications.
- Treat the event as a prompt, and the status read as the authority:

```js
async function handleEvent(event) {
  if (event.type !== 'kyc.session.completed') return;
  const response = await fetch(`https://collect.noxtica.com/v1/kyc/sessions/${event.data.sessionId}`, {
    headers: { Authorization: `Bearer ${process.env.NOXTICA_SERVER_KEY}` },
  });
  const { session } = await response.json();
  // Act on session.status. The "completed" status is the sole approval.
}
```

### 6. Rotate, disable or delete an endpoint

On the "Manage" tab of Backoffice → Integrations & API → Webhooks, each endpoint has these buttons:

- "Rotate secret" asks you to confirm "Rotate signing secret?". The current secret stops working immediately, with no overlap, and the new one is shown once. Update your receiver straight away. Retries still waiting are signed with the new secret.
- "Disable" stops deliveries to the endpoint and keeps it listed. "Enable" turns it back on.
- "Delete" removes the endpoint; deliveries to it stop immediately.

The tab has no editor for the event list of an existing endpoint. To change the events, delete the endpoint and add it again; the new endpoint has a new secret.

## Verify it works

1. On the endpoint row, select "Send test". Backoffice posts one signed sample, once, and shows "Test delivery succeeded" with the status and time. The row then shows the last status, for example `ok`.
2. Confirm that your receiver passed the signature check. The sample has the type `submission.scored`. It cannot produce an identity event, so it proves reachability and your signature code, not your identity handler.
3. Test the handler with a signed sample of your own for each identity event, or finish a hosted session from your server or from Backoffice → Identity Verification → KYC Invitations ("Create test session").
4. For a session or verification event, open Backoffice → Identity Verification → KYC → KYC Processes, select "View" on the process, and read the "Webhook deliveries" table. Its columns are Event, State, Attempts and Created. `delivered` means your endpoint answered `2xx`, `dead` means every retry failed, and `terminal` means a `4xx` or a refused URL ended it. The endpoint row's last status reflects "Send test" and non-identity events, not these deliveries.

## Troubleshooting

| Symptom | Cause | Fix |
| ------- | ----- | --- |
| "Send test" succeeds but no identity event arrives | The test sends `submission.scored`. The endpoint may not be subscribed to the identity event, may be disabled, or the event is not enabled for your organisation. | Check "Events to deliver", select "Enable" if needed, and ask your account team about gated events. |
| Signature check fails | The body was parsed and re-serialised, the secret is old after a rotation, the timestamp is read in seconds, or `created_at` was used instead of the header. | Hash the raw body, use the current secret, and use `X-Noxtica-Timestamp` in milliseconds. |
| Identity events never arrive for an endpoint that was created long ago | The endpoint was created before encrypted secret storage. Identity events are not delivered to it, and the delivery ends as `terminal`. | Select "Rotate secret" once, then update your receiver. |
| Events stop after you return `429` | Any `4xx` is final and is never retried. | Return `2xx` and queue the work. |
| An event arrives minutes after the reviewer's decision | Review decisions are sent on a periodic schedule. | Wait a few minutes. Read the status for the current state. |
| No event for `review_pending` or `expired` | Neither state sends an event. | Read the session status. |
| The same event arrives twice | Delivery is at least once, and an unconfirmed delivery can be sent again. | Deduplicate on `X-Noxtica-Delivery`. |
| A delivery shows `dead` | Every retry failed. | Fix the endpoint, then read the state from the status read. |
| "Send test" shows `blocked` or `http_0` | The URL is not a public HTTPS target. | Use a public HTTPS URL without credentials in it. |
| "That URL is already registered as a webhook endpoint" | The organisation has the URL already. | Use the existing endpoint, or delete it before you add it again. |
| "Webhook endpoints are limited to 25 per tenant" | The endpoint limit is reached. | Delete an endpoint you no longer use. |

## Related

- [Identity verification integration](https://noxtica.com/docs/identity-verification-integration/) — create sessions and read the status.
- [Noxtica Verification ID](https://noxtica.com/docs/identity-verification-id/) — the `nvid` field on events and the status read.
- [Business and merchant verification](https://noxtica.com/docs/identity-verification-business/) — `kyb.entity.*` and `kym.*` events.
- [Identity verification FAQ and troubleshooting](https://noxtica.com/docs/identity-verification-faq/) — duplicates, ordering and missing events.
- [Webhooks](https://noxtica.com/docs/api/webhooks/) — the generic envelope, headers and signature reference.
- [Errors](https://noxtica.com/docs/api/errors/) — error codes and the `requestId` to quote.

---

Source: https://noxtica.com/docs/backoffice/event-sinks/
Markdown: https://noxtica.com/docs/backoffice/event-sinks/index.md
Last updated: 2026-10-27

# Event sinks (SIEM export)

An event sink pushes Noxtica events to an HTTPS endpoint that you run, such as a SIEM collector. A workspace Admin creates the sink in Backoffice, arms it and checks delivery with a real test request. Use a sink when you want events in your own tooling without polling an API.

## What it is

Availability: Availability depends on your plan, role and the modules enabled for your organisation.

- **Where**: `Backoffice → Integrations & API → Event Sinks` (`/event-sinks`). The page title is **Event Sinks (SIEM)**. The sidebar item and the route need the Admin role.
- **What a sink holds**: a name (optional), an HTTPS endpoint, a format, a list of events, optional payload enrichments and a PII acknowledgement.
- **Events**: the sink subscribes to the same verdict event types as webhooks (see [Webhooks](https://noxtica.com/docs/api/webhooks/)), plus `audit.log` for the Backoffice audit stream and `compliance.evidence` for signed compliance evidence. A sink needs at least one event.
- **Payload enrichment**: the optional `incident.summary` token adds extra fields to every delivered record. It does not change which events are delivered.
- **Signing**: each sink has its own signing secret. Every delivery is an HMAC-signed HTTP POST, so your receiver can check it came from Noxtica.
- **Two keys for delivery**: creating a sink arms nothing. Delivery also needs your sink to be enabled and the platform event stream to be on for your workspace. If the page works but nothing arrives, the platform key is the usual reason; ask your account team.
- **Limit**: a workspace can hold up to 25 sinks.

Formats you can choose:

| Format label in Backoffice | Use for |
| --- | --- |
| Generic JSON webhook | Any HTTPS receiver that accepts JSON |
| Splunk HEC | Splunk HTTP Event Collector |
| Elasticsearch bulk (NDJSON) | Elasticsearch bulk endpoint |
| Google Chronicle (UDM) | Google Chronicle |
| CEF (ArcSight) | CEF receivers such as ArcSight |
| OCSF | OCSF-aware pipelines |
| Microsoft Sentinel | Azure Monitor ingestion with an Azure AD client-credentials flow |

## Prerequisites

- The Admin role and an authenticator app. Every change to a sink asks for a fresh MFA check. See [Backoffice guide](https://noxtica.com/docs/backoffice/overview/).
- A public `https://` endpoint that is ready to receive live traffic. Loopback, private, link-local and metadata addresses are refused, and a URL with embedded credentials is refused.
- A receiver that can verify an HMAC signature and answer with a 2xx status.
- For Microsoft Sentinel: the Azure tenant ID, the application (client) ID and a secure secret reference. Do not paste a client secret into the form.
- A decision on raw IP addresses. Raw IP is included in a sink's records only when your workspace stores raw IPs and you tick the PII acknowledgement on that sink. See [Data retention, raw IP storage and data locations](https://noxtica.com/docs/compliance/retention-and-locations/).

## Steps

### 1. Create the sink

1. Open `Event Sinks` and complete the form.
2. **Name (optional)**: for example "Splunk prod".
3. **HTTPS endpoint**: for example `https://siem.example.com/hec`.
4. **Format**: choose from the table above.
5. **Events**: tick the events this sink receives. Add **Payload enrichments** if you want them.
6. Leave **Acknowledge PII** unticked unless you need raw IP addresses.
7. Select **Create sink** and enter your MFA code.

The toast reads: "Event sink created (disabled). Copy the signing secret now — it is shown only once." A second sink with the same URL is refused with a 409 duplicate message.

### 2. Save the signing secret

The **Signing secret** box says it is "shown ONCE". Copy it into your receiver's configuration, then select **Dismiss**. Configure the receiver to verify the HMAC with it.

### 3. Verify each delivery in your receiver

Each request carries these headers:

| Header | Value |
| --- | --- |
| `X-Noxtica-Signature` | `sha256=` followed by the hex HMAC-SHA256 of `<timestamp>.<body>` with your signing secret |
| `X-Noxtica-Timestamp` | The Unix timestamp used in the signature |
| `X-Noxtica-Event` | The event type |
| `X-Noxtica-Delivery` | A delivery ID, useful for de-duplication |

Compute the HMAC over the timestamp, a dot and the raw request body. Answer quickly with a 2xx status and process the event afterwards. Each attempt has a 5 second timeout.

```js
// Node.js receiver sketch
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(rawBody, headers, secret) {
  const ts = headers['x-noxtica-timestamp'];
  const expected = 'sha256=' + createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  const got = headers['x-noxtica-signature'] ?? '';
  return got.length === expected.length && timingSafeEqual(Buffer.from(got), Buffer.from(expected));
}
```

Reject a request whose timestamp is far from your clock. Treat a repeated `X-Noxtica-Delivery` as a duplicate.

### 4. Arm the sink

The new sink has the status **disabled**. In the table, select **Enable** for the sink. The toast reads "Sink armed". Select **Disable** to stop delivery without deleting the sink.

### 5. Send a real test request

Select **Send real test request**. The dialog warns that this sends a real signed HTTPS request from Noxtica to your endpoint right now and records it as a delivery attempt. Select **Send real request**. On success the toast reads "Test delivery accepted by the endpoint (HTTP <status>)." The test uses the same SSRF guard and 5 second timeout as live delivery. Marked test probes are excluded from the delivery objective figures.

### 6. Inspect deliveries

Select **Deliveries** for a sink. The list shows the newest deliveries with **Status**, **Attempts**, **Last error** and **Created**, and a **Failed only** filter. Summary figures show success rate, last success and last failure. A delivery counts as a success when your endpoint answers 2xx. A 4xx answer is final. A 5xx answer, a network error or a timeout is retried.

The page also shows a **Seven-day delivery SLO** card. It counts recorded terminal HTTP acceptance only. It is not proof of ingestion in your SIEM and not proof that no events were lost, and an empty or unavailable observation is not healthy.

When recovery is available for a retained failure, **Redrive once** queues a single real delivery to the sink's current endpoint. The receiver may already have accepted the original event, so de-duplicate on `X-Noxtica-Delivery`. Redrive is single-use and depends on the feature being enabled for your organisation.

### 7. Rotate or delete

- **Rotate secret**: mints a new signing secret, shown once. The old secret stops working at once, so update your receiver first or accept failed verification until you do.
- **Delete sink**: removes the sink and stops all delivery to its URL. Deletion cannot be undone.

### 8. Microsoft Sentinel

Choosing **Microsoft Sentinel** adds fields for the Azure tenant ID, the application ID and a secret reference. Delivery uses an OAuth2 client-credentials flow instead of the HMAC signature. Noxtica refuses a form that carries an inline client secret.

## Verify it works

- The sink row shows **enabled** and a **Last delivery** time after the test.
- The test toast shows an HTTP 2xx status.
- **Deliveries** lists the test request as delivered.
- Your receiver logged the request and the signature check passed.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| "A https URL and at least one event type are required" | The endpoint is not `https`, or no event is ticked | Fix the URL and tick an event |
| Create fails with a duplicate message | A sink for this URL already exists | Edit the existing sink |
| Create fails with a limit message | The workspace has 25 sinks | Delete an unused sink |
| The test succeeds but live events never arrive | Sink is disabled, or the platform event stream is off for your workspace | Enable the sink; ask your account team |
| Signature check fails | Wrong secret, parsed body used instead of raw body, or timestamp not included | Recompute over `<timestamp>.<raw body>` with the current secret |
| Deliveries show repeated failures | Endpoint returns 5xx, times out or is blocked | Fix the receiver and check the 5 second timeout |
| Sentinel form is refused | A client secret was pasted inline | Use a secure secret reference |
| Every change asks for a code | Sink changes need a fresh MFA check | Enter the authenticator code |

## Related

- [Integrations and API pages](https://noxtica.com/docs/backoffice/integrations/): the map of this group.
- [Webhooks](https://noxtica.com/docs/api/webhooks/): event types and the shared signing scheme.
- [Audit log and data export](https://noxtica.com/docs/security/audit-log-and-exports/): what the `audit.log` stream carries.
- [Data retention, raw IP storage and data locations](https://noxtica.com/docs/compliance/retention-and-locations/): raw IP storage.
- [Roles and permissions](https://noxtica.com/docs/security/roles-and-permissions/): who can manage sinks.

---

Source: https://noxtica.com/docs/api/
Markdown: https://noxtica.com/docs/api/index.md
Last updated: 2026-10-27

# API overview

The Noxtica server APIs are HTTPS JSON APIs that your own back end calls. These pages are generated from the OpenAPI specifications that Noxtica publishes, so every route, parameter, field and status code listed here comes from the same source as the specification files.

The specifications themselves are published as files: [`/docs/api/openapi.json`](https://noxtica.com/docs/api/openapi.json) holds every public operation of the four APIs, and `/docs/api/openapi/<api>.json` holds one API each (`v1`, `kyc`, `pulse`, `mcp`); every file is also served as YAML, at the same address with the YAML extension. Import them into a client generator, an API workspace, or an AI agent. See [Integrate with an AI agent](https://noxtica.com/docs/ai-agents/).

Call these APIs from a server you control. A server API key is a secret and must never reach a browser or a mobile app. Availability is account-specific: the modules enabled for your account and the scopes on your key decide which operations you can call.

## Base URLs

Send each request to the base URL listed for the API you call.

| Environment | Base URL | Key prefix | APIs |
| --- | --- | --- | --- |
| Production | `https://collect.noxtica.com` | `sk_prod_` | [Identity verification API](https://noxtica.com/docs/api/reference/kyc/), [Risk scoring and agent trust API](https://noxtica.com/docs/api/reference/score/), [Protected actions API](https://noxtica.com/docs/api/reference/protected-actions/), [Device intelligence API](https://noxtica.com/docs/api/reference/device/), [Mobile and device identity API](https://noxtica.com/docs/api/reference/mobile/), [Telemetry ingestion API](https://noxtica.com/docs/api/reference/ingest/), [Observability query API](https://noxtica.com/docs/api/reference/observability/), [Health and public key endpoints](https://noxtica.com/docs/api/reference/status/) |
| Production ingest host | `https://ingest.noxtica.com` |  | [Telemetry ingestion API](https://noxtica.com/docs/api/reference/ingest/), [Observability query API](https://noxtica.com/docs/api/reference/observability/) |
| Production | `https://backoffice.noxtica.com` |  | [MCP server](https://noxtica.com/docs/api/reference/mcp/) |
| Production (not yet deployed) | `https://pulse.noxtica.com` |  | [Pulse tenant API](https://noxtica.com/docs/api/reference/pulse/) |

## Authentication

Operations authenticate with the credential named in their section. The credential formats are:

| Credential | Header | Used by |
| --- | --- | --- |
| `ApiKeyAuth` | `Authorization: Bearer sk_<random>` | [Identity verification API](https://noxtica.com/docs/api/reference/kyc/), [Risk scoring and agent trust API](https://noxtica.com/docs/api/reference/score/), [Protected actions API](https://noxtica.com/docs/api/reference/protected-actions/), [Device intelligence API](https://noxtica.com/docs/api/reference/device/), [Mobile and device identity API](https://noxtica.com/docs/api/reference/mobile/), [Observability query API](https://noxtica.com/docs/api/reference/observability/) |
| `SessionTokenAuth` | `Authorization: Bearer kycs.<tenant>.<secret>` | [Identity verification API](https://noxtica.com/docs/api/reference/kyc/) |
| `ApmIngestKeyAuth` | `Authorization: Bearer sk_apm_<random>` | [Telemetry ingestion API](https://noxtica.com/docs/api/reference/ingest/) |
| `CodingAgentKeyAuth` | `Authorization: Bearer cak_<random>` | [Observability query API](https://noxtica.com/docs/api/reference/observability/) |
| `McpTokenAuth` | `Authorization: Bearer mcp_<random>` | [MCP server](https://noxtica.com/docs/api/reference/mcp/) |
| `tenantKey` | `Authorization: Bearer sk_prod_<32 hex>` | [Pulse tenant API](https://noxtica.com/docs/api/reference/pulse/) |

See [Authentication](https://noxtica.com/docs/api/authentication/) for key handling and the scope each operation requires.

## Scopes

A key can call an operation only if it carries the scope the operation requires. The reference names 22 scopes; the [Authentication](https://noxtica.com/docs/api/authentication/) page lists the operations that need each one.

## Errors

Error responses use the HTTP status code and a JSON body that carries a machine-readable code and a request id. See [Errors](https://noxtica.com/docs/api/errors/) for the body, the codes each API returns and how to report a failed request.

## Rate limits

A request that exceeds a limit receives status `429` with a `Retry-After` header. See [Rate limits](https://noxtica.com/docs/api/rate-limits/) for how to back off and retry.

## Idempotency

These operations accept an `Idempotency-Key` header. Send a new, unique value for each logical operation and the same value when you retry it, so a retry cannot repeat the operation.

| Operation | Header | Length |
| --- | --- | --- |
| [`kycVerify`](https://noxtica.com/docs/api/reference/kyc/#kycVerify) | Required | 8 to 128 characters |
| [`kycVerifyBatchSubmit`](https://noxtica.com/docs/api/reference/kyc/#kycVerifyBatchSubmit) | Required | 8 to 128 characters |
| [`kycSessionMint`](https://noxtica.com/docs/api/reference/kyc/#kycSessionMint) | Optional | 8 to 128 characters |
| [`offlineCaptureBundleAdmit`](https://noxtica.com/docs/api/reference/mobile/#offlineCaptureBundleAdmit) | Required | 8 to 128 characters |

## Pagination

These operations return results in pages. Pass the cursor from one response, unchanged, in the `cursor` query parameter of the next request.

| Operation | Page size | Cursor in the response |
| --- | --- | --- |
| [`v1ListDevices`](https://noxtica.com/docs/api/reference/device/#v1ListDevices) | default 50, maximum 200 | `nextCursor` |
| [`v1ListAccountDevices`](https://noxtica.com/docs/api/reference/device/#v1ListAccountDevices) | default 50, maximum 200 | `nextCursor` |
| [`v1ListEvents`](https://noxtica.com/docs/api/reference/device/#v1ListEvents) | default 50, maximum 200 | `nextCursor` |
| [`v1ListVisits`](https://noxtica.com/docs/api/reference/device/#v1ListVisits) | default 50, maximum 200 | `nextCursor` |
| [`v1ExportFingerprints`](https://noxtica.com/docs/api/reference/device/#v1ExportFingerprints) |  | `X-Noxtica-Export-Next-Cursor`, `next_cursor` |
| [`v1ExportEvents`](https://noxtica.com/docs/api/reference/device/#v1ExportEvents) |  | `X-Noxtica-Export-Next-Cursor`, `next_cursor` |
| [`v1ExportVisits`](https://noxtica.com/docs/api/reference/device/#v1ExportVisits) |  | `X-Noxtica-Export-Next-Cursor`, `next_cursor` |
| [`v1ExportScoredEvents`](https://noxtica.com/docs/api/reference/device/#v1ExportScoredEvents) |  | `X-Noxtica-Export-Next-Cursor` |
| [`v1ListLabels`](https://noxtica.com/docs/api/reference/device/#v1ListLabels) | default 50, maximum 200 | `nextCursor` |
| [`v1ApmListProjects`](https://noxtica.com/docs/api/reference/observability/#v1ApmListProjects) | default 50, maximum 200 | `next_cursor` |
| [`v1ApmListProjectEnvironments`](https://noxtica.com/docs/api/reference/observability/#v1ApmListProjectEnvironments) | default 50, maximum 200 | `next_cursor` |
| [`v1ApmSearchTraces`](https://noxtica.com/docs/api/reference/observability/#v1ApmSearchTraces) | default 50, maximum 200 | `next_cursor` |
| [`pulseTenantListDecisions`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantListDecisions) | default 50, maximum 200 | `nextCursor` |

## Webhooks

Noxtica sends signed webhook deliveries for 11 event types: `kyc.session.completed`, `kyc.session.cancelled`, `kyc.verification.completed`, `kyc.erasure.completed`, `kyc.document.expiry_warning`, `kyc.reverification.due`, `submission.scored`, `risk.high`, `risk.flagged`, `risk.cluster_flagged`, `account.agent_linked`. See [Webhooks](https://noxtica.com/docs/api/webhooks/) for the headers, the signature and the event catalog.

## API reference

| API | What it covers | Operations | Credential |
| --- | --- | --- | --- |
| [Identity verification API](https://noxtica.com/docs/api/reference/kyc/) | Verify identities, run hosted verification sessions, batch and re-verify, store evidence, and receive signed KYC, KYB and KYM webhooks. | 25 | `ApiKeyAuth`, `SessionTokenAuth` |
| [Risk scoring and agent trust API](https://noxtica.com/docs/api/reference/score/) | Score a request, look up IP and device reputation, verify AI agents, and mint signed crawler vouchers from your server. | 7 | `ApiKeyAuth` |
| [Protected actions API](https://noxtica.com/docs/api/reference/protected-actions/) | Redeem the request id a browser obtains for a protected action (login, signup, checkout) before your server lets the action proceed. | 1 | `ApiKeyAuth` |
| [Device intelligence API](https://noxtica.com/docs/api/reference/device/) | Read devices, events and visits, export data, fetch the sealed-results key, write labels, and manage behavioral baselines. | 18 | `ApiKeyAuth` |
| [Mobile and device identity API](https://noxtica.com/docs/api/reference/mobile/) | Verify mobile attestation and integrity, deliver app configuration, and manage passkeys, handoff, delegation, recovery, wallet state and offline capture. | 22 | `ApiKeyAuth` |
| [Telemetry ingestion API](https://noxtica.com/docs/api/reference/ingest/) | Send OpenTelemetry traces, metrics, logs, profiles and deployment markers with an ingestion key. | 5 | `ApmIngestKeyAuth` |
| [Observability query API](https://noxtica.com/docs/api/reference/observability/) | Query projects, traces, services and releases, manage environment policy, run exports and privacy-request lookups, and read recent signals from a coding agent. | 17 | `ApiKeyAuth`, `CodingAgentKeyAuth` |
| [MCP server](https://noxtica.com/docs/api/reference/mcp/) | Connect an AI assistant or your own code to your workspace through the Model Context Protocol with a scoped token. | 1 | `McpTokenAuth` |
| [Pulse tenant API](https://noxtica.com/docs/api/reference/pulse/) | Read player status and decisions, create link codes, and manage links from your own back end with a tenant API key. | 7 | `tenantKey` |
| [Health and public key endpoints](https://noxtica.com/docs/api/reference/status/) | The unauthenticated collector health probe and the public signing-key documents for verifying signed envelopes and Agent Passports offline. | 3 | None |

_This page is generated from the Noxtica OpenAPI specification release `v0.4.0`: `kyc.yaml` version `1.2.0-2026-10-27` (SHA-256 `c91a695cfde0`), `mcp.yaml` version `0.1.0-2026-10-27` (SHA-256 `1a4875efa736`), `pulse.yaml` version `0.9.0-2026-10-27` (SHA-256 `95196a58bb5b`), `v1.yaml` version `1.3.0-2026-10-27` (SHA-256 `3fd15257a022`). Do not edit it by hand._

---

Source: https://noxtica.com/docs/api/errors/
Markdown: https://noxtica.com/docs/api/errors/index.md
Last updated: 2026-10-27

# API errors

A request that cannot be completed returns an HTTP status of `400` or higher and a JSON body. Branch on the status code first, then on the `error` or `code` value when the response carries one, and treat any value you do not recognise as a failure of that status class.

Every error body carries a request id. Log it with the failed call and quote it when you contact support.

## Error body

### Noxtica KYC / KYB / KYM API

| Field | Type | Always returned | Description |
| --- | --- | --- | --- |
| `error` | string | Yes |  |
| `requestId` | string | Yes |  |

### Noxtica Pulse customer, sign-in and device API

| Field | Type | Always returned | Description |
| --- | --- | --- | --- |
| `code` | string | Yes | Stable machine-readable identifier. |
| `error` | string | Yes |  |
| `message` | string | No |  |
| `requestId` | string | No |  |

### Noxtica Server API (/v1)

| Field | Type | Always returned | Description |
| --- | --- | --- | --- |
| `error` | string | Yes | Machine-readable error string; route-specific values are listed on each operation. |
| `requestId` | string | Yes | Correlation id for this call; quote it when you contact support. |

## Identity verification API: errors

Codes named in the responses of the Identity verification API operations.

| Status | Code | Returned by |
| --- | --- | --- |
| `400` | `consent_required` | [`kycSessionVerificationIdEmail`](https://noxtica.com/docs/api/reference/kyc/#kycSessionVerificationIdEmail) |
| `400` | `email_verification_unavailable` | [`kycSessionMint`](https://noxtica.com/docs/api/reference/kyc/#kycSessionMint) |
| `400` | `idempotency_key_invalid` | [`kycSessionSubmit`](https://noxtica.com/docs/api/reference/kyc/#kycSessionSubmit) |
| `400` | `Invalid sessionId` | [`kycSessionStatus`](https://noxtica.com/docs/api/reference/kyc/#kycSessionStatus) |
| `400` | `invalid_case_id` | [`kymTransactionsReport`](https://noxtica.com/docs/api/reference/kyc/#kymTransactionsReport) |
| `400` | `invalid_email` | [`kycSessionVerificationIdEmail`](https://noxtica.com/docs/api/reference/kyc/#kycSessionVerificationIdEmail), [`kycSessionEmailSend`](https://noxtica.com/docs/api/reference/kyc/#kycSessionEmailSend) |
| `400` | `invalid_hosted_options` | [`kycSessionMint`](https://noxtica.com/docs/api/reference/kyc/#kycSessionMint) |
| `400` | `invalid_id_type` | [`kycSessionMint`](https://noxtica.com/docs/api/reference/kyc/#kycSessionMint) |
| `400` | `invalid_or_expired` | [`kycEmailVerificationConfirm`](https://noxtica.com/docs/api/reference/kyc/#kycEmailVerificationConfirm) |
| `400` | `invalid_request` | [`kycVerify`](https://noxtica.com/docs/api/reference/kyc/#kycVerify), [`kycAddressDocumentCrossMatch`](https://noxtica.com/docs/api/reference/kyc/#kycAddressDocumentCrossMatch), [`kycVerifyBatchSubmit`](https://noxtica.com/docs/api/reference/kyc/#kycVerifyBatchSubmit), [`kycEvidenceHandleMint`](https://noxtica.com/docs/api/reference/kyc/#kycEvidenceHandleMint), and 10 more |
| `400` | `payload_invalid` | [`kycSessionSubmit`](https://noxtica.com/docs/api/reference/kyc/#kycSessionSubmit) |
| `400` | `return_url_not_allowed` | [`kycSessionMint`](https://noxtica.com/docs/api/reference/kyc/#kycSessionMint) |
| `401` | `invalid_api_key` | [`kycVerify`](https://noxtica.com/docs/api/reference/kyc/#kycVerify), [`kycAddressDocumentCrossMatch`](https://noxtica.com/docs/api/reference/kyc/#kycAddressDocumentCrossMatch), [`kycVerifyBatchSubmit`](https://noxtica.com/docs/api/reference/kyc/#kycVerifyBatchSubmit), [`kycVerifyBatchStatus`](https://noxtica.com/docs/api/reference/kyc/#kycVerifyBatchStatus), and 10 more |
| `401` | `invalid_session` | [`kycSessionCancel`](https://noxtica.com/docs/api/reference/kyc/#kycSessionCancel), [`kycSessionEmailSend`](https://noxtica.com/docs/api/reference/kyc/#kycSessionEmailSend), [`kycSessionEmailStatus`](https://noxtica.com/docs/api/reference/kyc/#kycSessionEmailStatus) |
| `402` | `spend_cap_reached` | [`kycVerify`](https://noxtica.com/docs/api/reference/kyc/#kycVerify) |
| `403` | `age_gender_estimation_not_enabled` | [`kycSessionMint`](https://noxtica.com/docs/api/reference/kyc/#kycSessionMint) |
| `403` | `API key does not have write:identity scope` | [`kycVerify`](https://noxtica.com/docs/api/reference/kyc/#kycVerify), [`kycAddressDocumentCrossMatch`](https://noxtica.com/docs/api/reference/kyc/#kycAddressDocumentCrossMatch), [`kycVerifyBatchSubmit`](https://noxtica.com/docs/api/reference/kyc/#kycVerifyBatchSubmit), [`kycVerifyBatchStatus`](https://noxtica.com/docs/api/reference/kyc/#kycVerifyBatchStatus), and 8 more |
| `403` | `invalid_request` | [`kycEvidenceFinalize`](https://noxtica.com/docs/api/reference/kyc/#kycEvidenceFinalize), [`kycSessionView`](https://noxtica.com/docs/api/reference/kyc/#kycSessionView), [`kycSessionProgress`](https://noxtica.com/docs/api/reference/kyc/#kycSessionProgress), [`kycSessionSubmit`](https://noxtica.com/docs/api/reference/kyc/#kycSessionSubmit), and 2 more |
| `403` | `kyc_legal_basis_receipt_required` | [`kycSessionMint`](https://noxtica.com/docs/api/reference/kyc/#kycSessionMint) |
| `403` | `origin_not_allowed` | [`kycSessionCancel`](https://noxtica.com/docs/api/reference/kyc/#kycSessionCancel), [`kycSessionVerificationIdEmail`](https://noxtica.com/docs/api/reference/kyc/#kycSessionVerificationIdEmail), [`kycSessionEmailSend`](https://noxtica.com/docs/api/reference/kyc/#kycSessionEmailSend), [`kycSessionEmailStatus`](https://noxtica.com/docs/api/reference/kyc/#kycSessionEmailStatus), and 2 more |
| `404` | `invalid_request` | [`kymTransactionsReport`](https://noxtica.com/docs/api/reference/kyc/#kymTransactionsReport) |
| `404` | `not_found` | [`kycVerificationIdStatus`](https://noxtica.com/docs/api/reference/kyc/#kycVerificationIdStatus) |
| `404` | `V1 endpoint not found` | [`kycVerify`](https://noxtica.com/docs/api/reference/kyc/#kycVerify), [`kycAddressDocumentCrossMatch`](https://noxtica.com/docs/api/reference/kyc/#kycAddressDocumentCrossMatch), [`kycVerifyBatchSubmit`](https://noxtica.com/docs/api/reference/kyc/#kycVerifyBatchSubmit), [`kycVerifyBatchStatus`](https://noxtica.com/docs/api/reference/kyc/#kycVerifyBatchStatus), and 19 more |
| `409` | `already_verified` | [`kycSessionEmailSend`](https://noxtica.com/docs/api/reference/kyc/#kycSessionEmailSend) |
| `409` | `email_verification_not_enabled` | [`kycSessionEmailSend`](https://noxtica.com/docs/api/reference/kyc/#kycSessionEmailSend), [`kycSessionEmailStatus`](https://noxtica.com/docs/api/reference/kyc/#kycSessionEmailStatus) |
| `409` | `email_verification_required` | [`kycSessionSubmit`](https://noxtica.com/docs/api/reference/kyc/#kycSessionSubmit) |
| `409` | `example-code` | [`kycVerify`](https://noxtica.com/docs/api/reference/kyc/#kycVerify) |
| `409` | `idempotency_conflict` | [`kycVerify`](https://noxtica.com/docs/api/reference/kyc/#kycVerify) |
| `409` | `invalid_request` | [`kycAddressDocumentCrossMatch`](https://noxtica.com/docs/api/reference/kyc/#kycAddressDocumentCrossMatch), [`kycSessionProgress`](https://noxtica.com/docs/api/reference/kyc/#kycSessionProgress), [`kycSessionSubmit`](https://noxtica.com/docs/api/reference/kyc/#kycSessionSubmit) |
| `409` | `session_expiring` | [`kycSessionEmailSend`](https://noxtica.com/docs/api/reference/kyc/#kycSessionEmailSend) |
| `409` | `session_not_cancellable` | [`kycSessionCancel`](https://noxtica.com/docs/api/reference/kyc/#kycSessionCancel) |
| `409` | `session_not_editable` | [`kycSessionEmailSend`](https://noxtica.com/docs/api/reference/kyc/#kycSessionEmailSend) |
| `409` | `session_not_submittable` | [`kycSessionSubmit`](https://noxtica.com/docs/api/reference/kyc/#kycSessionSubmit) |
| `409` | `verification_id_unavailable` | [`kycSessionVerificationIdEmail`](https://noxtica.com/docs/api/reference/kyc/#kycSessionVerificationIdEmail) |
| `409` | `verify_gate_consumed` | [`kycSessionSubmit`](https://noxtica.com/docs/api/reference/kyc/#kycSessionSubmit) |
| `410` | `kyc_session_cancelled` | [`kycSessionView`](https://noxtica.com/docs/api/reference/kyc/#kycSessionView), [`kycSessionProgress`](https://noxtica.com/docs/api/reference/kyc/#kycSessionProgress), [`kycSessionSubmit`](https://noxtica.com/docs/api/reference/kyc/#kycSessionSubmit), [`kycSessionVerificationIdEmail`](https://noxtica.com/docs/api/reference/kyc/#kycSessionVerificationIdEmail), and 4 more |
| `410` | `kyc_session_expired` | [`kycSessionCancel`](https://noxtica.com/docs/api/reference/kyc/#kycSessionCancel) |
| `410` | `session_cancelled` | [`kycSessionView`](https://noxtica.com/docs/api/reference/kyc/#kycSessionView), [`kycSessionProgress`](https://noxtica.com/docs/api/reference/kyc/#kycSessionProgress), [`kycSessionCancel`](https://noxtica.com/docs/api/reference/kyc/#kycSessionCancel), [`kycSessionSubmit`](https://noxtica.com/docs/api/reference/kyc/#kycSessionSubmit), and 5 more |
| `410` | `session_expired` | [`kycSessionCancel`](https://noxtica.com/docs/api/reference/kyc/#kycSessionCancel) |
| `413` | `body_too_large` | [`kycVerify`](https://noxtica.com/docs/api/reference/kyc/#kycVerify), [`kycAddressDocumentCrossMatch`](https://noxtica.com/docs/api/reference/kyc/#kycAddressDocumentCrossMatch), [`kycVerifyBatchSubmit`](https://noxtica.com/docs/api/reference/kyc/#kycVerifyBatchSubmit), [`kycEvidenceHandleMint`](https://noxtica.com/docs/api/reference/kyc/#kycEvidenceHandleMint), and 4 more |
| `415` | `invalid_request` | [`kycVerifyBatchSubmit`](https://noxtica.com/docs/api/reference/kyc/#kycVerifyBatchSubmit), [`kycSessionMint`](https://noxtica.com/docs/api/reference/kyc/#kycSessionMint) |
| `429` | `cooldown` | [`kycSessionEmailSend`](https://noxtica.com/docs/api/reference/kyc/#kycSessionEmailSend) |
| `429` | `invalid_request` | [`kycSessionSubmit`](https://noxtica.com/docs/api/reference/kyc/#kycSessionSubmit) |
| `429` | `Rate limit exceeded` | [`kycVerify`](https://noxtica.com/docs/api/reference/kyc/#kycVerify), [`kycAddressDocumentCrossMatch`](https://noxtica.com/docs/api/reference/kyc/#kycAddressDocumentCrossMatch), [`kycVerifyBatchSubmit`](https://noxtica.com/docs/api/reference/kyc/#kycVerifyBatchSubmit), [`kycEvidenceHandleMint`](https://noxtica.com/docs/api/reference/kyc/#kycEvidenceHandleMint), and 14 more |
| `429` | `rate_limited` | [`kycSessionVerificationIdEmail`](https://noxtica.com/docs/api/reference/kyc/#kycSessionVerificationIdEmail), [`kycVerificationIdStatus`](https://noxtica.com/docs/api/reference/kyc/#kycVerificationIdStatus) |
| `429` | `send_limit_reached` | [`kycSessionEmailSend`](https://noxtica.com/docs/api/reference/kyc/#kycSessionEmailSend) |
| `429` | `session_rate_limited` | [`kycSessionSubmit`](https://noxtica.com/docs/api/reference/kyc/#kycSessionSubmit) |
| `500` | `server_misconfigured` | [`kycSessionMint`](https://noxtica.com/docs/api/reference/kyc/#kycSessionMint), [`kycSessionStatus`](https://noxtica.com/docs/api/reference/kyc/#kycSessionStatus) |
| `502` | `email_send_failed` | [`kycSessionVerificationIdEmail`](https://noxtica.com/docs/api/reference/kyc/#kycSessionVerificationIdEmail), [`kycSessionEmailSend`](https://noxtica.com/docs/api/reference/kyc/#kycSessionEmailSend) |
| `503` | `email_unavailable` | [`kycSessionVerificationIdEmail`](https://noxtica.com/docs/api/reference/kyc/#kycSessionVerificationIdEmail) |
| `503` | `hosted_verify_not_configured` | [`kycSessionSubmit`](https://noxtica.com/docs/api/reference/kyc/#kycSessionSubmit), [`kycSessionEmailSend`](https://noxtica.com/docs/api/reference/kyc/#kycSessionEmailSend) |
| `503` | `invalid_request` | [`kycVerify`](https://noxtica.com/docs/api/reference/kyc/#kycVerify), [`kycAddressDocumentCrossMatch`](https://noxtica.com/docs/api/reference/kyc/#kycAddressDocumentCrossMatch), [`kycVerifyBatchSubmit`](https://noxtica.com/docs/api/reference/kyc/#kycVerifyBatchSubmit), [`kycEvidenceHandleMint`](https://noxtica.com/docs/api/reference/kyc/#kycEvidenceHandleMint), and 8 more |
| `503` | `kyc_legal_basis_receipt_unavailable` | [`kycSessionSubmit`](https://noxtica.com/docs/api/reference/kyc/#kycSessionSubmit) |
| `503` | `nonce_mint_unavailable` | [`kycSessionSubmit`](https://noxtica.com/docs/api/reference/kyc/#kycSessionSubmit) |
| `503` | `session_backend_unavailable` | [`kycSessionEmailSend`](https://noxtica.com/docs/api/reference/kyc/#kycSessionEmailSend), [`kycSessionEmailStatus`](https://noxtica.com/docs/api/reference/kyc/#kycSessionEmailStatus) |
| `503` | `submit_internal_error` | [`kycSessionSubmit`](https://noxtica.com/docs/api/reference/kyc/#kycSessionSubmit) |
| `503` | `temporarily_unavailable` | [`kycEmailVerificationConfirm`](https://noxtica.com/docs/api/reference/kyc/#kycEmailVerificationConfirm), [`kycVerificationIdStatus`](https://noxtica.com/docs/api/reference/kyc/#kycVerificationIdStatus) |
| `503` | `write_failed` | [`kymTransactionsReport`](https://noxtica.com/docs/api/reference/kyc/#kymTransactionsReport) |

## Risk scoring and agent trust API: errors

Codes named in the responses of the Risk scoring and agent trust API operations.

| Status | Code | Returned by |
| --- | --- | --- |
| `400` | `Invalid body` | [`v1VerifyReputation`](https://noxtica.com/docs/api/reference/score/#v1VerifyReputation), [`postAgentVerify`](https://noxtica.com/docs/api/reference/score/#postAgentVerify), [`postIpReputation`](https://noxtica.com/docs/api/reference/score/#postIpReputation), [`postScore`](https://noxtica.com/docs/api/reference/score/#postScore) |
| `400` | `invalid_request` | [`v1MintCrawlVoucher`](https://noxtica.com/docs/api/reference/score/#v1MintCrawlVoucher) |
| `401` | `invalid_api_key` | [`v1VerifyReputation`](https://noxtica.com/docs/api/reference/score/#v1VerifyReputation), [`v1MintCrawlVoucher`](https://noxtica.com/docs/api/reference/score/#v1MintCrawlVoucher), [`getAgentPassport`](https://noxtica.com/docs/api/reference/score/#getAgentPassport), [`postAgentPassport`](https://noxtica.com/docs/api/reference/score/#postAgentPassport), and 3 more |
| `402` | `invalid_request` | [`v1MintCrawlVoucher`](https://noxtica.com/docs/api/reference/score/#v1MintCrawlVoucher) |
| `403` | `API key does not have read:device scope` | [`v1VerifyReputation`](https://noxtica.com/docs/api/reference/score/#v1VerifyReputation), [`v1MintCrawlVoucher`](https://noxtica.com/docs/api/reference/score/#v1MintCrawlVoucher), [`postAgentVerify`](https://noxtica.com/docs/api/reference/score/#postAgentVerify), [`postIpReputation`](https://noxtica.com/docs/api/reference/score/#postIpReputation), and 1 more |
| `403` | `feature disabled` | [`getAgentPassport`](https://noxtica.com/docs/api/reference/score/#getAgentPassport), [`postAgentPassport`](https://noxtica.com/docs/api/reference/score/#postAgentPassport) |
| `404` | `Not found` | [`getAgentPassport`](https://noxtica.com/docs/api/reference/score/#getAgentPassport), [`postAgentPassport`](https://noxtica.com/docs/api/reference/score/#postAgentPassport) |
| `404` | `V1 endpoint not found` | [`v1VerifyReputation`](https://noxtica.com/docs/api/reference/score/#v1VerifyReputation) |
| `413` | `body_too_large` | [`v1MintCrawlVoucher`](https://noxtica.com/docs/api/reference/score/#v1MintCrawlVoucher), [`postAgentVerify`](https://noxtica.com/docs/api/reference/score/#postAgentVerify) |
| `413` | `invalid_request` | [`postAgentPassport`](https://noxtica.com/docs/api/reference/score/#postAgentPassport) |
| `415` | `invalid_request` | [`v1MintCrawlVoucher`](https://noxtica.com/docs/api/reference/score/#v1MintCrawlVoucher), [`postAgentVerify`](https://noxtica.com/docs/api/reference/score/#postAgentVerify) |
| `429` | `Rate limit exceeded` | [`v1VerifyReputation`](https://noxtica.com/docs/api/reference/score/#v1VerifyReputation), [`v1MintCrawlVoucher`](https://noxtica.com/docs/api/reference/score/#v1MintCrawlVoucher), [`getAgentPassport`](https://noxtica.com/docs/api/reference/score/#getAgentPassport), [`postAgentPassport`](https://noxtica.com/docs/api/reference/score/#postAgentPassport), and 3 more |
| `500` | `Internal server error` | [`v1VerifyReputation`](https://noxtica.com/docs/api/reference/score/#v1VerifyReputation), [`v1MintCrawlVoucher`](https://noxtica.com/docs/api/reference/score/#v1MintCrawlVoucher), [`postAgentVerify`](https://noxtica.com/docs/api/reference/score/#postAgentVerify), [`postIpReputation`](https://noxtica.com/docs/api/reference/score/#postIpReputation), and 1 more |
| `500` | `invalid_request` | [`getAgentPassport`](https://noxtica.com/docs/api/reference/score/#getAgentPassport), [`postAgentPassport`](https://noxtica.com/docs/api/reference/score/#postAgentPassport) |
| `503` | `invalid_request` | [`v1MintCrawlVoucher`](https://noxtica.com/docs/api/reference/score/#v1MintCrawlVoucher), [`getAgentPassport`](https://noxtica.com/docs/api/reference/score/#getAgentPassport), [`postAgentPassport`](https://noxtica.com/docs/api/reference/score/#postAgentPassport) |

## Protected actions API: errors

Codes named in the responses of the Protected actions API operations.

| Status | Code | Returned by |
| --- | --- | --- |
| `400` | `invalid_action` | [`postProtectedActionsVerify`](https://noxtica.com/docs/api/reference/protected-actions/#postProtectedActionsVerify) |
| `400` | `invalid_body` | [`postProtectedActionsVerify`](https://noxtica.com/docs/api/reference/protected-actions/#postProtectedActionsVerify) |
| `400` | `invalid_expected_domain` | [`postProtectedActionsVerify`](https://noxtica.com/docs/api/reference/protected-actions/#postProtectedActionsVerify) |
| `400` | `invalid_request_id` | [`postProtectedActionsVerify`](https://noxtica.com/docs/api/reference/protected-actions/#postProtectedActionsVerify) |
| `401` | `invalid_api_key` | [`postProtectedActionsVerify`](https://noxtica.com/docs/api/reference/protected-actions/#postProtectedActionsVerify) |
| `403` | `API key does not have read:device scope` | [`postProtectedActionsVerify`](https://noxtica.com/docs/api/reference/protected-actions/#postProtectedActionsVerify) |
| `404` | `request_not_found` | [`postProtectedActionsVerify`](https://noxtica.com/docs/api/reference/protected-actions/#postProtectedActionsVerify) |
| `409` | `already_consumed` | [`postProtectedActionsVerify`](https://noxtica.com/docs/api/reference/protected-actions/#postProtectedActionsVerify) |
| `413` | `payload_too_large` | [`postProtectedActionsVerify`](https://noxtica.com/docs/api/reference/protected-actions/#postProtectedActionsVerify) |
| `422` | `action_mismatch` | [`postProtectedActionsVerify`](https://noxtica.com/docs/api/reference/protected-actions/#postProtectedActionsVerify) |
| `422` | `domain_mismatch` | [`postProtectedActionsVerify`](https://noxtica.com/docs/api/reference/protected-actions/#postProtectedActionsVerify) |
| `429` | `Rate limit exceeded` | [`postProtectedActionsVerify`](https://noxtica.com/docs/api/reference/protected-actions/#postProtectedActionsVerify) |
| `500` | `Internal server error` | [`postProtectedActionsVerify`](https://noxtica.com/docs/api/reference/protected-actions/#postProtectedActionsVerify) |

## Device intelligence API: errors

Codes named in the responses of the Device intelligence API operations.

| Status | Code | Returned by |
| --- | --- | --- |
| `400` | `invalid_request` | [`v1GetDevice`](https://noxtica.com/docs/api/reference/device/#v1GetDevice), [`v1ListDevices`](https://noxtica.com/docs/api/reference/device/#v1ListDevices), [`v1ListAccountDevices`](https://noxtica.com/docs/api/reference/device/#v1ListAccountDevices), [`v1ListEvents`](https://noxtica.com/docs/api/reference/device/#v1ListEvents), and 11 more |
| `401` | `invalid_api_key` | [`v1GetDevice`](https://noxtica.com/docs/api/reference/device/#v1GetDevice), [`v1ListDevices`](https://noxtica.com/docs/api/reference/device/#v1ListDevices), [`v1ListAccountDevices`](https://noxtica.com/docs/api/reference/device/#v1ListAccountDevices), [`v1ListEvents`](https://noxtica.com/docs/api/reference/device/#v1ListEvents), and 14 more |
| `403` | `API key does not have read:device scope` | [`v1GetDevice`](https://noxtica.com/docs/api/reference/device/#v1GetDevice), [`v1ListDevices`](https://noxtica.com/docs/api/reference/device/#v1ListDevices), [`v1ListAccountDevices`](https://noxtica.com/docs/api/reference/device/#v1ListAccountDevices), [`v1ListEvents`](https://noxtica.com/docs/api/reference/device/#v1ListEvents), and 13 more |
| `403` | `invalid_request` | [`v1GetSealedResultsKey`](https://noxtica.com/docs/api/reference/device/#v1GetSealedResultsKey) |
| `404` | `Device not found` | [`v1GetDevice`](https://noxtica.com/docs/api/reference/device/#v1GetDevice) |
| `404` | `invalid_request` | [`v1GenerateFingerprintBatch`](https://noxtica.com/docs/api/reference/device/#v1GenerateFingerprintBatch), [`v1GenerateSingleFingerprint`](https://noxtica.com/docs/api/reference/device/#v1GenerateSingleFingerprint), [`v1GetBehavioralSubject`](https://noxtica.com/docs/api/reference/device/#v1GetBehavioralSubject), [`v1EraseBehavioralSubject`](https://noxtica.com/docs/api/reference/device/#v1EraseBehavioralSubject), and 1 more |
| `404` | `sealed_key_version_unavailable` | [`v1GetSealedResultsKey`](https://noxtica.com/docs/api/reference/device/#v1GetSealedResultsKey) |
| `404` | `sealed-results key version unavailable` | [`v1GetSealedResultsKey`](https://noxtica.com/docs/api/reference/device/#v1GetSealedResultsKey) |
| `413` | `body_too_large` | [`v1WriteLabel`](https://noxtica.com/docs/api/reference/device/#v1WriteLabel), [`v1GenerateFingerprintBatch`](https://noxtica.com/docs/api/reference/device/#v1GenerateFingerprintBatch), [`v1GenerateSingleFingerprint`](https://noxtica.com/docs/api/reference/device/#v1GenerateSingleFingerprint) |
| `415` | `invalid_request` | [`v1WriteLabel`](https://noxtica.com/docs/api/reference/device/#v1WriteLabel), [`v1GenerateFingerprintBatch`](https://noxtica.com/docs/api/reference/device/#v1GenerateFingerprintBatch), [`v1GenerateSingleFingerprint`](https://noxtica.com/docs/api/reference/device/#v1GenerateSingleFingerprint) |
| `429` | `Rate limit exceeded` | [`v1GetDevice`](https://noxtica.com/docs/api/reference/device/#v1GetDevice), [`v1ListDevices`](https://noxtica.com/docs/api/reference/device/#v1ListDevices), [`v1ListAccountDevices`](https://noxtica.com/docs/api/reference/device/#v1ListAccountDevices), [`v1ListEvents`](https://noxtica.com/docs/api/reference/device/#v1ListEvents), and 12 more |
| `500` | `Internal server error` | [`v1GetDevice`](https://noxtica.com/docs/api/reference/device/#v1GetDevice), [`v1ListEvents`](https://noxtica.com/docs/api/reference/device/#v1ListEvents), [`v1ListVisits`](https://noxtica.com/docs/api/reference/device/#v1ListVisits), [`v1ExportFingerprints`](https://noxtica.com/docs/api/reference/device/#v1ExportFingerprints), and 12 more |
| `500` | `invalid_request` | [`v1ListDevices`](https://noxtica.com/docs/api/reference/device/#v1ListDevices), [`v1ListAccountDevices`](https://noxtica.com/docs/api/reference/device/#v1ListAccountDevices) |
| `500` | `server_misconfigured` | [`v1GetSealedResultsKey`](https://noxtica.com/docs/api/reference/device/#v1GetSealedResultsKey) |
| `502` | `invalid_request` | [`v1EraseBehavioralSubject`](https://noxtica.com/docs/api/reference/device/#v1EraseBehavioralSubject) |

## Mobile and device identity API: errors

Codes named in the responses of the Mobile and device identity API operations.

| Status | Code | Returned by |
| --- | --- | --- |
| `400` | `device_delegation_invalid_subject_id` | [`deviceDelegationCreate`](https://noxtica.com/docs/api/reference/mobile/#deviceDelegationCreate) |
| `400` | `invalid_request` | [`postAttestAndroid`](https://noxtica.com/docs/api/reference/mobile/#postAttestAndroid), [`postAttestIos`](https://noxtica.com/docs/api/reference/mobile/#postAttestIos), [`postAttestVerify`](https://noxtica.com/docs/api/reference/mobile/#postAttestVerify), [`postAttestChallenge`](https://noxtica.com/docs/api/reference/mobile/#postAttestChallenge), and 14 more |
| `400` | `offline_capture_nonce_invalid` | [`offlineCaptureBundleAdmit`](https://noxtica.com/docs/api/reference/mobile/#offlineCaptureBundleAdmit) |
| `400` | `offline_capture_verdict_claim_rejected` | [`offlineCaptureBundleAdmit`](https://noxtica.com/docs/api/reference/mobile/#offlineCaptureBundleAdmit) |
| `401` | `invalid_api_key` | [`postAttestAndroid`](https://noxtica.com/docs/api/reference/mobile/#postAttestAndroid), [`postAttestIos`](https://noxtica.com/docs/api/reference/mobile/#postAttestIos), [`postAttestVerify`](https://noxtica.com/docs/api/reference/mobile/#postAttestVerify), [`postAttestChallenge`](https://noxtica.com/docs/api/reference/mobile/#postAttestChallenge), and 18 more |
| `403` | `API key does not have read:device scope` | [`postAttestAndroid`](https://noxtica.com/docs/api/reference/mobile/#postAttestAndroid), [`postAttestIos`](https://noxtica.com/docs/api/reference/mobile/#postAttestIos), [`postAttestVerify`](https://noxtica.com/docs/api/reference/mobile/#postAttestVerify), [`postAttestChallenge`](https://noxtica.com/docs/api/reference/mobile/#postAttestChallenge), and 15 more |
| `403` | `API key does not have write:identity:trusted-subject scope` | [`walletSuspend`](https://noxtica.com/docs/api/reference/mobile/#walletSuspend) |
| `403` | `invalid_request` | [`offlineNoncePoolMint`](https://noxtica.com/docs/api/reference/mobile/#offlineNoncePoolMint), [`offlineCaptureBundleAdmit`](https://noxtica.com/docs/api/reference/mobile/#offlineCaptureBundleAdmit) |
| `403` | `kyc_legal_basis_receipt_required` | [`offlineNoncePoolMint`](https://noxtica.com/docs/api/reference/mobile/#offlineNoncePoolMint), [`offlineCaptureBundleAdmit`](https://noxtica.com/docs/api/reference/mobile/#offlineCaptureBundleAdmit) |
| `404` | `invalid_request` | [`deviceDelegationRevoke`](https://noxtica.com/docs/api/reference/mobile/#deviceDelegationRevoke) |
| `404` | `V1 endpoint not found` | [`postAttestAndroid`](https://noxtica.com/docs/api/reference/mobile/#postAttestAndroid), [`postAttestIos`](https://noxtica.com/docs/api/reference/mobile/#postAttestIos), [`postPasskeyChallenge`](https://noxtica.com/docs/api/reference/mobile/#postPasskeyChallenge), [`postPasskeyRegister`](https://noxtica.com/docs/api/reference/mobile/#postPasskeyRegister), and 13 more |
| `409` | `invalid_request` | [`offlineCaptureBundleAdmit`](https://noxtica.com/docs/api/reference/mobile/#offlineCaptureBundleAdmit) |
| `409` | `offline_capture_idempotency_conflict` | [`offlineCaptureBundleAdmit`](https://noxtica.com/docs/api/reference/mobile/#offlineCaptureBundleAdmit) |
| `409` | `offline_capture_nonce_replayed` | [`offlineCaptureBundleAdmit`](https://noxtica.com/docs/api/reference/mobile/#offlineCaptureBundleAdmit) |
| `410` | `invalid_request` | [`offlineCaptureBundleAdmit`](https://noxtica.com/docs/api/reference/mobile/#offlineCaptureBundleAdmit) |
| `410` | `offline_capture_bundle_expired` | [`offlineCaptureBundleAdmit`](https://noxtica.com/docs/api/reference/mobile/#offlineCaptureBundleAdmit) |
| `413` | `body_too_large` | [`postAttestAndroid`](https://noxtica.com/docs/api/reference/mobile/#postAttestAndroid), [`postAttestIos`](https://noxtica.com/docs/api/reference/mobile/#postAttestIos), [`postAttestVerify`](https://noxtica.com/docs/api/reference/mobile/#postAttestVerify), [`postAttestChallenge`](https://noxtica.com/docs/api/reference/mobile/#postAttestChallenge), and 8 more |
| `413` | `invalid_request` | [`postAppConfig`](https://noxtica.com/docs/api/reference/mobile/#postAppConfig), [`postHandoffMint`](https://noxtica.com/docs/api/reference/mobile/#postHandoffMint), [`postHandoffConsume`](https://noxtica.com/docs/api/reference/mobile/#postHandoffConsume), [`offlineCaptureBundleAdmit`](https://noxtica.com/docs/api/reference/mobile/#offlineCaptureBundleAdmit) |
| `415` | `invalid_request` | [`postAttestAndroid`](https://noxtica.com/docs/api/reference/mobile/#postAttestAndroid), [`postAttestIos`](https://noxtica.com/docs/api/reference/mobile/#postAttestIos), [`postAttestVerify`](https://noxtica.com/docs/api/reference/mobile/#postAttestVerify), [`postAttestChallenge`](https://noxtica.com/docs/api/reference/mobile/#postAttestChallenge), and 7 more |
| `429` | `Rate limit exceeded` | [`postAttestAndroid`](https://noxtica.com/docs/api/reference/mobile/#postAttestAndroid), [`postAttestIos`](https://noxtica.com/docs/api/reference/mobile/#postAttestIos), [`postAttestVerify`](https://noxtica.com/docs/api/reference/mobile/#postAttestVerify), [`postAttestChallenge`](https://noxtica.com/docs/api/reference/mobile/#postAttestChallenge), and 18 more |
| `500` | `Internal server error` | [`postAttestAndroid`](https://noxtica.com/docs/api/reference/mobile/#postAttestAndroid), [`postAttestIos`](https://noxtica.com/docs/api/reference/mobile/#postAttestIos), [`postAppConfig`](https://noxtica.com/docs/api/reference/mobile/#postAppConfig), [`postPasskeyChallenge`](https://noxtica.com/docs/api/reference/mobile/#postPasskeyChallenge), and 4 more |
| `503` | `device_delegation_storage_unavailable` | [`deviceDelegationCreate`](https://noxtica.com/docs/api/reference/mobile/#deviceDelegationCreate), [`deviceDelegationList`](https://noxtica.com/docs/api/reference/mobile/#deviceDelegationList), [`deviceDelegationRevoke`](https://noxtica.com/docs/api/reference/mobile/#deviceDelegationRevoke) |
| `503` | `invalid_request` | [`postAttestAndroid`](https://noxtica.com/docs/api/reference/mobile/#postAttestAndroid), [`postAttestIos`](https://noxtica.com/docs/api/reference/mobile/#postAttestIos), [`deviceDelegationCreate`](https://noxtica.com/docs/api/reference/mobile/#deviceDelegationCreate), [`deviceDelegationList`](https://noxtica.com/docs/api/reference/mobile/#deviceDelegationList), and 3 more |
| `503` | `kyc_first_party_provenance_unavailable` | [`offlineNoncePoolMint`](https://noxtica.com/docs/api/reference/mobile/#offlineNoncePoolMint), [`offlineCaptureBundleAdmit`](https://noxtica.com/docs/api/reference/mobile/#offlineCaptureBundleAdmit) |
| `503` | `offline_capture_storage_unavailable` | [`offlineNoncePoolMint`](https://noxtica.com/docs/api/reference/mobile/#offlineNoncePoolMint), [`offlineCaptureBundleAdmit`](https://noxtica.com/docs/api/reference/mobile/#offlineCaptureBundleAdmit) |
| `503` | `registry_write_failed` | [`recoveryOpenCase`](https://noxtica.com/docs/api/reference/mobile/#recoveryOpenCase), [`recoveryGetCase`](https://noxtica.com/docs/api/reference/mobile/#recoveryGetCase), [`recoveryOpenAppeal`](https://noxtica.com/docs/api/reference/mobile/#recoveryOpenAppeal), [`recoveryGetAppeal`](https://noxtica.com/docs/api/reference/mobile/#recoveryGetAppeal) |

## Telemetry ingestion API: errors

Codes named in the responses of the Telemetry ingestion API operations.

| Status | Code | Returned by |
| --- | --- | --- |
| `400` | `apm_invalid_payload` | [`v1ApmIngestDeploymentMarker`](https://noxtica.com/docs/api/reference/ingest/#v1ApmIngestDeploymentMarker) |
| `400` | `apm_malformed_json` | [`v1ApmIngestDeploymentMarker`](https://noxtica.com/docs/api/reference/ingest/#v1ApmIngestDeploymentMarker) |
| `400` | `apm_malformed_logs_payload` | [`v1ApmIngestLogs`](https://noxtica.com/docs/api/reference/ingest/#v1ApmIngestLogs) |
| `400` | `apm_malformed_metrics_payload` | [`v1ApmIngestMetrics`](https://noxtica.com/docs/api/reference/ingest/#v1ApmIngestMetrics) |
| `400` | `apm_malformed_otlp_json` | [`v1ApmIngestTraces`](https://noxtica.com/docs/api/reference/ingest/#v1ApmIngestTraces) |
| `400` | `apm_malformed_profile_json` | [`v1ApmIngestProfiles`](https://noxtica.com/docs/api/reference/ingest/#v1ApmIngestProfiles) |
| `401` | `apm_auth_expired` | [`v1ApmIngestDeploymentMarker`](https://noxtica.com/docs/api/reference/ingest/#v1ApmIngestDeploymentMarker) |
| `403` | `apm_environment_mismatch` | [`v1ApmIngestDeploymentMarker`](https://noxtica.com/docs/api/reference/ingest/#v1ApmIngestDeploymentMarker) |
| `413` | `apm_body_too_large` | [`v1ApmIngestDeploymentMarker`](https://noxtica.com/docs/api/reference/ingest/#v1ApmIngestDeploymentMarker) |
| `415` | `apm_unsupported_media_type` | [`v1ApmIngestDeploymentMarker`](https://noxtica.com/docs/api/reference/ingest/#v1ApmIngestDeploymentMarker) |
| `429` | `apm_rate_limited` | [`v1ApmIngestDeploymentMarker`](https://noxtica.com/docs/api/reference/ingest/#v1ApmIngestDeploymentMarker) |
| `503` | `apm_authority_unavailable` | [`v1ApmIngestDeploymentMarker`](https://noxtica.com/docs/api/reference/ingest/#v1ApmIngestDeploymentMarker) |
| `503` | `apm_profile_storage_unavailable` | [`v1ApmIngestProfiles`](https://noxtica.com/docs/api/reference/ingest/#v1ApmIngestProfiles) |

## Observability query API: errors

Codes named in the responses of the Observability query API operations.

| Status | Code | Returned by |
| --- | --- | --- |
| `400` | `invalid_request` | [`v1ApmListProjects`](https://noxtica.com/docs/api/reference/observability/#v1ApmListProjects), [`v1ApmListProjectEnvironments`](https://noxtica.com/docs/api/reference/observability/#v1ApmListProjectEnvironments), [`v1ApmGetEnvironmentPolicy`](https://noxtica.com/docs/api/reference/observability/#v1ApmGetEnvironmentPolicy), [`v1ApmUpdateEnvironmentPolicy`](https://noxtica.com/docs/api/reference/observability/#v1ApmUpdateEnvironmentPolicy), and 10 more |
| `400` | `schema_invalid` | [`codingAgentListFindings`](https://noxtica.com/docs/api/reference/observability/#codingAgentListFindings) |
| `401` | `coding_agent_auth_invalid` | [`codingAgentListFindings`](https://noxtica.com/docs/api/reference/observability/#codingAgentListFindings), [`codingAgentGetTrace`](https://noxtica.com/docs/api/reference/observability/#codingAgentGetTrace), [`codingAgentGetErrorGroup`](https://noxtica.com/docs/api/reference/observability/#codingAgentGetErrorGroup) |
| `401` | `coding_agent_auth_missing` | [`codingAgentListFindings`](https://noxtica.com/docs/api/reference/observability/#codingAgentListFindings), [`codingAgentGetTrace`](https://noxtica.com/docs/api/reference/observability/#codingAgentGetTrace), [`codingAgentGetErrorGroup`](https://noxtica.com/docs/api/reference/observability/#codingAgentGetErrorGroup) |
| `401` | `Unauthorized` | [`v1ApmListProjects`](https://noxtica.com/docs/api/reference/observability/#v1ApmListProjects), [`v1ApmListProjectEnvironments`](https://noxtica.com/docs/api/reference/observability/#v1ApmListProjectEnvironments), [`v1ApmGetEnvironmentPolicy`](https://noxtica.com/docs/api/reference/observability/#v1ApmGetEnvironmentPolicy), [`v1ApmUpdateEnvironmentPolicy`](https://noxtica.com/docs/api/reference/observability/#v1ApmUpdateEnvironmentPolicy), and 10 more |
| `403` | `API key does not have read:apm scope` | [`v1ApmListProjects`](https://noxtica.com/docs/api/reference/observability/#v1ApmListProjects), [`v1ApmListProjectEnvironments`](https://noxtica.com/docs/api/reference/observability/#v1ApmListProjectEnvironments), [`v1ApmGetEnvironmentPolicy`](https://noxtica.com/docs/api/reference/observability/#v1ApmGetEnvironmentPolicy), [`v1ApmUpdateEnvironmentPolicy`](https://noxtica.com/docs/api/reference/observability/#v1ApmUpdateEnvironmentPolicy), and 10 more |
| `403` | `coding_agent_scope_denied` | [`codingAgentGetTrace`](https://noxtica.com/docs/api/reference/observability/#codingAgentGetTrace), [`codingAgentGetErrorGroup`](https://noxtica.com/docs/api/reference/observability/#codingAgentGetErrorGroup) |
| `404` | `coding_agent_error_group_not_found` | [`codingAgentGetErrorGroup`](https://noxtica.com/docs/api/reference/observability/#codingAgentGetErrorGroup) |
| `404` | `resource_not_found` | [`v1ApmListProjectEnvironments`](https://noxtica.com/docs/api/reference/observability/#v1ApmListProjectEnvironments), [`v1ApmGetEnvironmentPolicy`](https://noxtica.com/docs/api/reference/observability/#v1ApmGetEnvironmentPolicy), [`v1ApmUpdateEnvironmentPolicy`](https://noxtica.com/docs/api/reference/observability/#v1ApmUpdateEnvironmentPolicy), [`v1ApmSearchTraces`](https://noxtica.com/docs/api/reference/observability/#v1ApmSearchTraces), and 9 more |
| `409` | `capture_unavailable` | [`v1ApmUpdateEnvironmentPolicy`](https://noxtica.com/docs/api/reference/observability/#v1ApmUpdateEnvironmentPolicy) |
| `429` | `coding_agent_rate_limited` | [`codingAgentListFindings`](https://noxtica.com/docs/api/reference/observability/#codingAgentListFindings), [`codingAgentGetTrace`](https://noxtica.com/docs/api/reference/observability/#codingAgentGetTrace), [`codingAgentGetErrorGroup`](https://noxtica.com/docs/api/reference/observability/#codingAgentGetErrorGroup) |
| `429` | `Rate limit exceeded` | [`v1ApmListProjects`](https://noxtica.com/docs/api/reference/observability/#v1ApmListProjects), [`v1ApmListProjectEnvironments`](https://noxtica.com/docs/api/reference/observability/#v1ApmListProjectEnvironments), [`v1ApmGetEnvironmentPolicy`](https://noxtica.com/docs/api/reference/observability/#v1ApmGetEnvironmentPolicy), [`v1ApmSearchTraces`](https://noxtica.com/docs/api/reference/observability/#v1ApmSearchTraces), and 8 more |
| `500` | `internal_error` | [`v1ApmSearchTraces`](https://noxtica.com/docs/api/reference/observability/#v1ApmSearchTraces), [`v1ApmGetTrace`](https://noxtica.com/docs/api/reference/observability/#v1ApmGetTrace) |
| `502` | `coding_agent_query_failed` | [`codingAgentListFindings`](https://noxtica.com/docs/api/reference/observability/#codingAgentListFindings), [`codingAgentGetTrace`](https://noxtica.com/docs/api/reference/observability/#codingAgentGetTrace), [`codingAgentGetErrorGroup`](https://noxtica.com/docs/api/reference/observability/#codingAgentGetErrorGroup) |
| `503` | `coding_agent_authority_unavailable` | [`codingAgentListFindings`](https://noxtica.com/docs/api/reference/observability/#codingAgentListFindings), [`codingAgentGetTrace`](https://noxtica.com/docs/api/reference/observability/#codingAgentGetTrace), [`codingAgentGetErrorGroup`](https://noxtica.com/docs/api/reference/observability/#codingAgentGetErrorGroup) |
| `503` | `coding_agent_bq_unavailable` | [`codingAgentListFindings`](https://noxtica.com/docs/api/reference/observability/#codingAgentListFindings), [`codingAgentGetTrace`](https://noxtica.com/docs/api/reference/observability/#codingAgentGetTrace), [`codingAgentGetErrorGroup`](https://noxtica.com/docs/api/reference/observability/#codingAgentGetErrorGroup) |

## MCP server: errors

Codes named in the responses of the MCP server operations.

| Status | Code | Returned by |
| --- | --- | --- |
| `401` | `unauthorized` | [`mcpJsonRpc`](https://noxtica.com/docs/api/reference/mcp/#mcpJsonRpc) |
| `404` | `not_found` | [`mcpJsonRpc`](https://noxtica.com/docs/api/reference/mcp/#mcpJsonRpc) |
| `429` | `rate_limited` | [`mcpJsonRpc`](https://noxtica.com/docs/api/reference/mcp/#mcpJsonRpc) |
| `500` | `internal_error` | [`mcpJsonRpc`](https://noxtica.com/docs/api/reference/mcp/#mcpJsonRpc) |

## Pulse tenant API: errors

Codes named in the responses of the Pulse tenant API operations.

| Status | Code | Returned by |
| --- | --- | --- |
| `400` | `invalid_cursor` | [`pulseTenantListDecisions`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantListDecisions) |
| `400` | `invalid_parameter` | [`pulseTenantCreateLinkCode`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantCreateLinkCode), [`pulseTenantGetLink`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantGetLink), [`pulseTenantUnlink`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantUnlink) |
| `400` | `invalid_request` | [`pulseTenantListDecisions`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantListDecisions), [`pulseTenantReverseDecision`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantReverseDecision) |
| `400` | `invalid_subject` | [`pulseTenantSubjectStatus`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantSubjectStatus), [`pulseTenantGetLink`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantGetLink), [`pulseTenantUnlink`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantUnlink) |
| `401` | `invalid_api_key` | [`pulseTenantSubjectStatus`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantSubjectStatus), [`pulseTenantListDecisions`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantListDecisions), [`pulseTenantGetDecision`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantGetDecision), [`pulseTenantReverseDecision`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantReverseDecision), and 3 more |
| `401` | `missing_api_key` | [`pulseTenantSubjectStatus`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantSubjectStatus), [`pulseTenantListDecisions`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantListDecisions), [`pulseTenantGetDecision`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantGetDecision), [`pulseTenantReverseDecision`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantReverseDecision), and 3 more |
| `403` | `insufficient_scope` | [`pulseTenantSubjectStatus`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantSubjectStatus), [`pulseTenantListDecisions`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantListDecisions), [`pulseTenantGetDecision`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantGetDecision), [`pulseTenantReverseDecision`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantReverseDecision), and 3 more |
| `403` | `scope_not_granted` | [`pulseTenantListDecisions`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantListDecisions) |
| `403` | `tenant_not_armed` | [`pulseTenantSubjectStatus`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantSubjectStatus), [`pulseTenantListDecisions`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantListDecisions), [`pulseTenantGetDecision`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantGetDecision), [`pulseTenantReverseDecision`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantReverseDecision), and 3 more |
| `404` | `application_not_found` | [`pulseTenantCreateLinkCode`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantCreateLinkCode) |
| `404` | `decision_not_found` | [`pulseTenantGetDecision`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantGetDecision), [`pulseTenantReverseDecision`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantReverseDecision) |
| `404` | `subject_not_found` | [`pulseTenantSubjectStatus`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantSubjectStatus), [`pulseTenantListDecisions`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantListDecisions), [`pulseTenantGetLink`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantGetLink), [`pulseTenantUnlink`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantUnlink) |
| `409` | `ambiguous_subject` | [`pulseTenantSubjectStatus`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantSubjectStatus), [`pulseTenantGetLink`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantGetLink), [`pulseTenantUnlink`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantUnlink) |
| `409` | `external_user_already_linked` | [`pulseTenantCreateLinkCode`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantCreateLinkCode) |
| `409` | `hint_not_active` | [`pulseTenantReverseDecision`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantReverseDecision) |
| `429` | `rate_limited` | [`pulseTenantCreateLinkCode`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantCreateLinkCode) |
| `429` | `too_many_outstanding_codes` | [`pulseTenantCreateLinkCode`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantCreateLinkCode) |
| `503` | `rate_limiter_unavailable` | [`pulseTenantSubjectStatus`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantSubjectStatus), [`pulseTenantCreateLinkCode`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantCreateLinkCode), [`pulseTenantGetLink`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantGetLink), [`pulseTenantUnlink`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantUnlink) |
| `503` | `tenant_auth_unavailable` | [`pulseTenantSubjectStatus`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantSubjectStatus), [`pulseTenantCreateLinkCode`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantCreateLinkCode), [`pulseTenantGetLink`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantGetLink), [`pulseTenantUnlink`](https://noxtica.com/docs/api/reference/pulse/#pulseTenantUnlink) |

## Health and public key endpoints: errors

Codes named in the responses of the Health and public key endpoints operations.

| Status | Code | Returned by |
| --- | --- | --- |
| `404` | `Not found` | [`getCollectorJwks`](https://noxtica.com/docs/api/reference/status/#getCollectorJwks), [`getAgentPassportJwks`](https://noxtica.com/docs/api/reference/status/#getAgentPassportJwks) |
| `429` | `Rate limit exceeded` | [`getHealth`](https://noxtica.com/docs/api/reference/status/#getHealth) |

_This page is generated from the Noxtica OpenAPI specification release `v0.4.0`: `kyc.yaml` version `1.2.0-2026-10-27` (SHA-256 `c91a695cfde0`), `mcp.yaml` version `0.1.0-2026-10-27` (SHA-256 `1a4875efa736`), `pulse.yaml` version `0.9.0-2026-10-27` (SHA-256 `95196a58bb5b`), `v1.yaml` version `1.3.0-2026-10-27` (SHA-256 `3fd15257a022`). Do not edit it by hand._

---

Source: https://noxtica.com/docs/api/rate-limits/
Markdown: https://noxtica.com/docs/api/rate-limits/index.md
Last updated: 2026-10-27

# API rate limits

Noxtica limits how often a caller can use an operation. Limits depend on the operation and on your account, so this page describes the mechanism and does not list figures. Do not hard-code a limit: the response tells you when to try again.

## What a limited request returns

A request over its limit is rejected with HTTP status `429` and a JSON body. The `Retry-After` header holds the number of seconds to wait before the next request.

| Header | Meaning |
| --- | --- |
| `Retry-After` | Seconds until the bucket allows another request. |

| Field | Type | Always returned | Description |
| --- | --- | --- | --- |
| `error` | string | No | Allowed values: `Rate limit exceeded`. |
| `retryAfter` | integer | No |  |
| `requestId` | string | No |  |

Example body:

```json
{
  "error": "Rate limit exceeded",
  "retryAfter": 1,
  "requestId": "req-test"
}
```

| Header | Meaning |
| --- | --- |
| `Retry-After` | Seconds until the window resets. |

| Field | Type | Always returned | Description |
| --- | --- | --- | --- |
| `code` | string | Yes | Stable machine-readable identifier. |
| `error` | string | Yes |  |
| `message` | string | No |  |
| `requestId` | string | No |  |

| Header | Meaning |
| --- | --- |
| `Retry-After` | Seconds until the bucket allows another request. |

| Field | Type | Always returned | Description |
| --- | --- | --- | --- |
| `error` | string | Yes | Allowed values: `Rate limit exceeded`. |
| `retryAfter` | integer | Yes | Seconds to wait; equals the `Retry-After` header. |
| `requestId` | string | No |  |

Example body:

```json
{
  "error": "Rate limit exceeded",
  "retryAfter": 12,
  "requestId": "req-test"
}
```

## How to retry

1. Stop sending requests for the operation until the `Retry-After` period has passed.
2. Retry the request once, then increase the wait on each further `429`, with random jitter, up to a maximum you choose.
3. Retry only requests that are safe to repeat. For an operation that creates something, send an `Idempotency-Key` where the operation accepts one so a retry cannot create a second copy.
4. Spread bulk work over time instead of sending it in one burst.

_This page is generated from the Noxtica OpenAPI specification release `v0.4.0`: `kyc.yaml` version `1.2.0-2026-10-27` (SHA-256 `c91a695cfde0`), `mcp.yaml` version `0.1.0-2026-10-27` (SHA-256 `1a4875efa736`), `pulse.yaml` version `0.9.0-2026-10-27` (SHA-256 `95196a58bb5b`), `v1.yaml` version `1.3.0-2026-10-27` (SHA-256 `3fd15257a022`). Do not edit it by hand._

---

Source: https://noxtica.com/docs/api/reference/
Markdown: https://noxtica.com/docs/api/reference/index.md
Last updated: 2026-10-27

# API reference

The reference has one page for each API area. Every operation on a page has its own anchor, which is the `operationId` of the operation in the OpenAPI specification, so a link such as `/docs/api/reference/<area>/#<operationId>` always points at one operation.

## API areas

| API | What it covers | Operations | Credential |
| --- | --- | --- | --- |
| [Identity verification API](https://noxtica.com/docs/api/reference/kyc/) | Verify identities, run hosted verification sessions, batch and re-verify, store evidence, and receive signed KYC, KYB and KYM webhooks. | 25 | `ApiKeyAuth`, `SessionTokenAuth` |
| [Risk scoring and agent trust API](https://noxtica.com/docs/api/reference/score/) | Score a request, look up IP and device reputation, verify AI agents, and mint signed crawler vouchers from your server. | 7 | `ApiKeyAuth` |
| [Protected actions API](https://noxtica.com/docs/api/reference/protected-actions/) | Redeem the request id a browser obtains for a protected action (login, signup, checkout) before your server lets the action proceed. | 1 | `ApiKeyAuth` |
| [Device intelligence API](https://noxtica.com/docs/api/reference/device/) | Read devices, events and visits, export data, fetch the sealed-results key, write labels, and manage behavioral baselines. | 18 | `ApiKeyAuth` |
| [Mobile and device identity API](https://noxtica.com/docs/api/reference/mobile/) | Verify mobile attestation and integrity, deliver app configuration, and manage passkeys, handoff, delegation, recovery, wallet state and offline capture. | 22 | `ApiKeyAuth` |
| [Telemetry ingestion API](https://noxtica.com/docs/api/reference/ingest/) | Send OpenTelemetry traces, metrics, logs, profiles and deployment markers with an ingestion key. | 5 | `ApmIngestKeyAuth` |
| [Observability query API](https://noxtica.com/docs/api/reference/observability/) | Query projects, traces, services and releases, manage environment policy, run exports and privacy-request lookups, and read recent signals from a coding agent. | 17 | `ApiKeyAuth`, `CodingAgentKeyAuth` |
| [MCP server](https://noxtica.com/docs/api/reference/mcp/) | Connect an AI assistant or your own code to your workspace through the Model Context Protocol with a scoped token. | 1 | `McpTokenAuth` |
| [Pulse tenant API](https://noxtica.com/docs/api/reference/pulse/) | Read player status and decisions, create link codes, and manage links from your own back end with a tenant API key. | 7 | `tenantKey` |
| [Health and public key endpoints](https://noxtica.com/docs/api/reference/status/) | The unauthenticated collector health probe and the public signing-key documents for verifying signed envelopes and Agent Passports offline. | 3 | None |

## Shared conventions

The credentials, errors, rate limits and webhooks that apply to every area are described once: start with the [API overview](https://noxtica.com/docs/api/), then read [Authentication](https://noxtica.com/docs/api/authentication/), [Errors](https://noxtica.com/docs/api/errors/), [Rate limits](https://noxtica.com/docs/api/rate-limits/) and [Webhooks](https://noxtica.com/docs/api/webhooks/).

_This page is generated from the Noxtica OpenAPI specification release `v0.4.0`: `kyc.yaml` version `1.2.0-2026-10-27` (SHA-256 `c91a695cfde0`), `mcp.yaml` version `0.1.0-2026-10-27` (SHA-256 `1a4875efa736`), `pulse.yaml` version `0.9.0-2026-10-27` (SHA-256 `95196a58bb5b`), `v1.yaml` version `1.3.0-2026-10-27` (SHA-256 `3fd15257a022`). Do not edit it by hand._

---

Source: https://noxtica.com/docs/api/mcp/
Markdown: https://noxtica.com/docs/api/mcp/index.md
Last updated: 2026-10-27

# Connect an MCP client

Connect an AI assistant or your own code to your workspace through the Model Context Protocol with a scoped token.

## Endpoint

| Environment | Base URL |
| --- | --- |
| Production | `https://backoffice.noxtica.com` |

### Scope

The MCP server is one HTTPS endpoint, `POST /api/mcp`, on the Backoffice host:
`https://backoffice.noxtica.com` (production). It speaks JSON-RPC 2.0 over a synchronous HTTP POST. It is not part of the
collector API and is not consumed by the SDK family; this file describes the HTTP envelope
and the JSON-RPC methods. The catalogue of tools is **not** listed here: it depends on the
token, so call `tools/list` for the tools your token may use.

### Authentication

Send `Authorization: Bearer mcp_...`, where the token is an MCP token created in the
Backoffice under Integrations & API, MCP tokens (the secret is shown once). The server uses a
static opaque bearer token, **not** OAuth: it sends no `WWW-Authenticate` challenge and
exposes no OAuth metadata, so configure your MCP client with a custom `Authorization`
header. A token lives at most 90 days and also expires after 90 days without use. A revoked,
expired or unknown token gets HTTP `401`.

A token is either a *read* token or a *write* token and carries scopes. Scopes are the
ceiling of what a token can do: `tools/list` shows only the tools a token's scopes and tool
allowlist permit, and a tool outside them answers JSON-RPC error `-32001` (a tool that does
not exist for the token answers `-32002`). A write token can only *plan* a management
change; it can never apply one: a person approves every plan in the Backoffice.

### Methods

| Method | Purpose |
|---|---|
| `initialize` | Server information and capabilities. |
| `tools/list` | The tools this token may call, with their input schemas. |
| `tools/call` | Call one tool: `params: {"name": "...", "arguments": {...}}`. The result is one text content item holding JSON. |
| `resources/list`, `resources/templates/list`, `resources/read` | Public-content resources, available only for tokens that are allowed to read them; otherwise `-32601`. |

The protocol version answered by `initialize` is `2024-11-05`. A client that asks for
`2025-03-26` in `initialize.params.protocolVersion` gets that version when streamable
transport is enabled for the deployment; the server then also answers the same JSON-RPC
response as a single `text/event-stream` message when the request carries
`Accept: text/event-stream`. Otherwise the answer is always a plain JSON body.

### Errors

Transport-level failures use the HTTP status and a small JSON body:
`401 {"error":"unauthorized"}`, `404 {"error":"not_found"}` (MCP is not enabled for the
deployment), `429 {"error":"rate_limited"}` and `500 {"error":"internal_error"}`. Everything
else is a JSON-RPC error carried in an HTTP `200` body, including an unparseable body
(`-32700`). Branch on the numeric `error.code`; see `JsonRpcError`.

### Rate limits and limits

Each token has a request limit; a request over it answers `429` with `Retry-After` and the
headers `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (Unix seconds)
and `X-RateLimit-Bucket`, which are also sent on successful responses of this endpoint.
`tools/call` and resource reads are additionally limited to 60 calls per 60 seconds per
token; going over answers `-32004` with `error.data.retryAfterSeconds`. A monthly query
allowance applies to tool calls and resource reads (`-32003` when used up, `-32005` when the
plan does not include MCP). A serialized tool result may be at most 200 KB; a larger one
answers `-32602`, so lower the `limit` argument of the tool. The request body may be at most
1 MB.

## Operations

The full request and response description of each operation is in the [MCP server](https://noxtica.com/docs/api/reference/mcp/) reference.

| Operation | Request | Summary |
| --- | --- | --- |
| [`mcpJsonRpc`](https://noxtica.com/docs/api/reference/mcp/#mcpJsonRpc) | `POST /api/mcp` | Send one MCP JSON-RPC request |

_This page is generated from the Noxtica OpenAPI specification release `v0.4.0`: `kyc.yaml` version `1.2.0-2026-10-27` (SHA-256 `c91a695cfde0`), `mcp.yaml` version `0.1.0-2026-10-27` (SHA-256 `1a4875efa736`), `pulse.yaml` version `0.9.0-2026-10-27` (SHA-256 `95196a58bb5b`), `v1.yaml` version `1.3.0-2026-10-27` (SHA-256 `3fd15257a022`). Do not edit it by hand._

---

Source: https://noxtica.com/docs/concepts/mcp-integration/
Markdown: https://noxtica.com/docs/concepts/mcp-integration/index.md
Last updated: 2026-10-27

# MCP Integration

**Definition.** Noxtica's Model Context Protocol (MCP) integration gives an eligible tenant's external AI workflow structured, **read-only** access to supported Noxtica context. The surface uses MCP over JSON-RPC and requires a scoped bearer token.

It solves a context problem: an internal assistant or investigation workflow may need current policy, alert, or risk-distribution information without a person copying it from the console. MCP makes approved reads machine-consumable while leaving action and authorization in customer-owned systems.

Two boundaries define the integration:

- **Read-only.** An MCP client cannot change Noxtica configuration, create a policy, or act on traffic.
- **Opt-in and tenant-scoped.** MCP is off by default, enabled only for eligible tenants, and restricted to the tenant and scopes associated with the issued token.

## When it applies

MCP is useful when a security, fraud, support, or reporting workflow already uses an MCP-compatible client and needs Noxtica context for:

- summarizing a tenant's current policies or rules;
- adding recent alerts to an investigation brief;
- describing risk distribution for an operational review; or
- answering a bounded question before a human opens the source record.

If a workflow needs to update Noxtica, enforce a traffic decision, or combine data across tenants, this integration does not provide that capability.

## How customers use it

1. Confirm MCP eligibility and request tenant enablement.
2. Have an authorized operator create a token with only the required read scopes.
3. Configure the MCP-compatible client with the provisioned server details and token.
4. Request a supported read and inspect the structured response.
5. Route the result to a human review, report, or customer-owned automation with its own permissions.
6. Review call history, and mint or revoke tokens under your normal access process.

Connection details and available tools are provided during tenant provisioning; do not infer undocumented endpoints or scopes from examples.

## How Noxtica does it

MCP is the open protocol boundary. Noxtica applies product access controls before returning tenant information and records calls for review.

### Authentication

Bearer tokens have three customer-facing controls:

- **Scoped** — a token can read only the enabled surfaces represented by its scopes.
- **Rate-limited** — requests are subject to the tenant's provisioned limits.
- **Audited** — calls are recorded, including denied calls, so operators can review what was requested and when.

Treat the token as a secret. Give each integration the narrowest useful scope, keep it out of browser code and prompts, and revoke it and mint a new one when ownership changes.

### The read-only tool set

Subject to tenant enablement and token scope, the current read surface can include:

- **Policies** — configured policy context.
- **Rules** — rules used by supported decision workflows.
- **Alerts** — recent tenant alerts.
- **Risk distribution** — aggregate risk context for the tenant's traffic.

Every tool is a read. Responses are data for the client to interpret, not instructions and not permission to take an action. The connected agent cannot use MCP to change Noxtica or customer infrastructure.

## Outputs and decisions

| MCP output              | How it can inform a decision                                         |
| ----------------------- | -------------------------------------------------------------------- |
| Policy and rule context | Check whether an observed result matches the intended tenant posture |
| Recent alerts           | Prioritize which event or period a human should investigate          |
| Risk distribution       | Compare current traffic mix with the team's expected operating range |
| Call audit record       | Review which integration requested which Noxtica context             |

An MCP response can become stale after configuration or traffic changes. For customer-impacting decisions, retrieve current source records and apply the customer's normal authorization and review controls.

## Eligibility and limitations

- MCP requires explicit tenant enablement and provisioned connection details; there is no anonymous or self-serve connection.
- The integration is read-only even if the connected client supports write-capable tools elsewhere.
- Tokens do not bypass operator roles, tenant boundaries, scopes, or rate limits.
- Supported tools can differ by tenant provisioning. An absent tool is not an invitation to call an undocumented API.
- MCP does not verify the identity or trustworthiness of agents arriving at your site; that is the separate [KYA](https://noxtica.com/docs/concepts/know-your-agent/) concern.

## Where it fits

MCP is the "you integrate agentically" part of [Agentic Security](https://noxtica.com/docs/concepts/agentic-security/). It is distinct from the [AI Assistant](https://noxtica.com/docs/concepts/ai-assistant/) inside the console and from [Know Your Agent](https://noxtica.com/docs/concepts/know-your-agent/), which evaluates supported incoming-agent identities.

## Who it fits

MCP fits a security, fraud, support or reporting workflow that already uses an MCP-compatible client. The uses are listed under [When it applies](https://noxtica.com/docs/concepts/mcp-integration/#when-it-applies): investigation briefs, policy summaries and operations reporting.

## How teams connect

Connection details come from your tenant provisioning; the steps are under [How customers use it](https://noxtica.com/docs/concepts/mcp-integration/#how-customers-use-it). Tokens are created in Backoffice: a workspace Admin mints and revokes tokens after a fresh multi-factor check, and tokens expire. See [AI assistant, MCP tokens and coding-agent keys](https://noxtica.com/docs/backoffice/ai-assistant-and-mcp/). The endpoint, protocol and tool list are in [MCP server](https://noxtica.com/docs/api/mcp/).

## Limits

MCP is a read path into tenant telemetry, not a control path.

- **Controlled availability.** MCP access follows the tenant's plan tier and operator gates. Connections are set up with Noxtica.
- Scores and risk levels in responses are probabilistic and can be wrong. Your team decides what to do, and is responsible for the client and model it connects. See [Calibration](https://noxtica.com/docs/concepts/calibration/).

What the tools can and cannot do is under [The read-only tool set](https://noxtica.com/docs/concepts/mcp-integration/#the-read-only-tool-set). Enablement rules and stale responses are under [Eligibility and limitations](https://noxtica.com/docs/concepts/mcp-integration/#eligibility-and-limitations) and [Outputs and decisions](https://noxtica.com/docs/concepts/mcp-integration/#outputs-and-decisions).

## Common questions

### Can an AI client change my Noxtica settings?

No. The tools are read-only. See [The read-only tool set](https://noxtica.com/docs/concepts/mcp-integration/#the-read-only-tool-set).

### Can anyone connect an AI client?

No. Every connection needs a token issued by an authorized operator, and access is gated as described under [Limits](https://noxtica.com/docs/concepts/mcp-integration/#limits).

### How is MCP different from the AI assistant?

The [AI Assistant](https://noxtica.com/docs/concepts/ai-assistant/) serves a signed-in operator inside the console. MCP serves an approved external client that reads scoped data with a token. They are provisioned separately.

## Read deeper

- [Agentic Security](https://noxtica.com/docs/concepts/agentic-security/) — how external reads, operator investigation, and incoming-agent governance differ.
- [AI Assistant](https://noxtica.com/docs/concepts/ai-assistant/) — the operator-side read experience.
- [Features: AI-assisted operations](https://noxtica.com/docs/features/#ai-assisted-operations) — the assistant and MCP customer surfaces.
- [Backend integration](https://noxtica.com/docs/backend-integration/) — supported Server API device reads for application code.
- [Contact](https://noxtica.com/contact/) — confirm MCP eligibility and enablement.

---

Source: https://noxtica.com/docs/backoffice/ai-assistant-and-mcp/
Markdown: https://noxtica.com/docs/backoffice/ai-assistant-and-mcp/index.md
Last updated: 2026-10-27

# AI assistant, MCP tokens and coding-agent keys

Backoffice has three AI-related surfaces. The **assistant** is a chat panel for operators. **MCP Tokens** let an outside AI client read workspace data through the Model Context Protocol. **Coding Agent Keys** let a coding agent read your errors, traces and logs. A workspace Admin sets all three up and keeps each one to the narrowest access it needs.

## What it is

Availability: Availability depends on your plan, role and the modules enabled for your organisation.

| Surface | Where | Who uses it | What it reads or does |
| --- | --- | --- | --- |
| Assistant | Floating **Assistant** button on every page | Admin and above | Answers questions about your workspace inside your own role and workspace |
| LLM Routing, Speech, LLM Provider Keys | `/ai/llm-routing`, `/ai/speech`, `/ai/provider-keys` | Admin | Where model calls go, voice features, your own provider keys |
| MCP Tokens | `/integrations/mcp-tokens` | Admin | Bearer tokens for an MCP client |
| Coding Agent Keys | `/integrations/coding-agent-keys` | Admin | Read-only keys for a coding agent |

How they differ from the concept pages: [AI Assistant](https://noxtica.com/docs/concepts/ai-assistant/) describes the operator copilot and [MCP Integration](https://noxtica.com/docs/concepts/mcp-integration/) describes the external read surface. The wire protocol, endpoint and tool list for MCP are in [MCP server](https://noxtica.com/docs/api/mcp/). This page covers the Backoffice side.

Treat every answer as a signal. The assistant says "AI-generated — may be inaccurate or incomplete. Not advice. Verify independently before acting." An MCP or coding-agent response is data for your own tooling to interpret.

## Prerequisites

- The Admin role. Lower roles do not see the assistant button or these pages. See [Backoffice guide](https://noxtica.com/docs/backoffice/overview/).
- An authenticator app. Minting a token or key, and changing assistant configuration, ask for a fresh MFA check.
- The assistant enabled for your organisation. When it is not, opening it shows "Assistant not enabled". When it is enabled but no provider is configured, it shows "Configuration pending". A tenant-level switch can also turn AI off for a workspace.
- For MCP Tokens: MCP enabled for your organisation. The page says the MCP server stays disabled until an operator turns it on.
- A secret store. Tokens and keys are shown once.

## Steps

### 1. Use the assistant

1. Select the **Assistant** button (bottom-right by default). Drag it to another corner, or focus it and press an arrow key to move it.
2. Ask a bounded question about your workspace, for example about policies, domains, fingerprints or the audit log.
3. Use the toolbar for **New chat**, **Save**, **Sessions**, the **Assistant model** picker, **Dock to the right** or **Dock to the bottom**, **Minimize** and **Maximize**. The panel is a helper: it does not block the page behind it.

What to expect:

- The assistant answers within your role and the active workspace.
- Answers show the data they were based on under **Sources**, or "No tenant data was read for this answer."
- Credits: the panel shows your monthly AI credits remaining. When they run out it says so and they reset at the start of the next month (UTC).
- Sessions: **Usage & export** lists your sessions with model, token cost and status, never their contents. When available, conversation text is kept for 30 days in a size-capped record that only you can see; you can export or erase it. If retention is off for your workspace, text is never stored on the server.
- Voice: when speech is enabled, dictation inserts a transcript for review and sends nothing until you press **Send**. Read-aloud plays an answer.
- Changes: write actions are off by default. Where they are enabled, the assistant only proposes a change. A **plan** shows the diff, and a person approves it with a fresh MFA check. The assistant cannot apply a change itself.

### 2. Choose model routing (LLM Routing)

`AI & Agents → LLM Routing` offers three modes: **Platform default**, **Prefer local** (use a locally running model when one is available, otherwise fall back silently) and **Require local (data residency)** (never send the workspace's data to a cloud model; a task with no matching local model fails). The section describes the setting as the model choice for the workstation Backoffice Agent's tasks for this workspace. Pick **Save**.

### 3. Set speech and your own provider keys

- `Speech`: shows which voice features are available and why any are off. Add your own speech provider key if you do not want to use the platform pool. Usage appears on **Usage & Quotas**.
- `LLM Provider Keys`: add a key for a provider you have an account with. Keys are stored encrypted and never shown again. Choose a **Data policy** for each key: **Tier-safe** (eligible to serve assistant turns once it has a model) or **Dev only** (can be tested, cannot serve assistant turns; OpenRouter is always dev only). Use **Discover models**, pick a **Default model**, and **Test** the credential. If you remove a key while using your own keys only, assistant turns stop when no other eligible key can serve them; the platform does not take over.

### 4. Mint an MCP token

1. Open `Integrations & API → MCP Tokens`. Tabs: **Manage** and **Integration** (an in-app guide).
2. Enter a **Name** of 2 to 200 characters that identifies the client that will hold it.
3. Choose read scopes. Scopes are grouped by area: Workspace & usage, Detection analytics, Devices, Noxtica Pulse, Rules & disputes, Alerts, Session replay, Governance, Agent Worker, Published content, RUM, APM & runtime tracker, KYC, KYB & KYM, SEO, Billing & wallet, Workspace settings & integrations, Infrastructure, Team & credential inventory. Each read scope names what it exposes, for example **Device scores & related devices** or **Audit log**.
4. Optionally restrict the tools the token can call, and set an expiry.
5. Select the create button, enter your MFA code, and copy the token. It is shown once.

Rules Backoffice enforces:

- The token is bound to your workspace, and it can never carry a permission that you do not hold.
- Expiry is mandatory and bounded. If you give none, the token expires 90 days after creation. A longer date is reduced to 90 days, and a date in the past is refused. A token that sits idle can also expire.
- A token has a summary or detail tier that changes how fine-grained the read results are. The tier never widens the token's column allowlist.
- Revoke a token to cut off any client at once. The row shows **Last used**.
- Write tokens exist only when write tokens are enabled for your organisation; otherwise minting one is refused. An agent that holds a write token can only plan a change. The plan appears under **Pending AI-agent plans** for 24 hours. You approve it with a fresh MFA check within 10 minutes, or reject it. If the token is revoked, the plan is cancelled.

Connect your client with the endpoint, headers and rate limits in [MCP server](https://noxtica.com/docs/api/mcp/). **Agentic Security → MCP token usage** shows queries used against the period limit. See [Risk actions, investigations and entity lookup](https://noxtica.com/docs/backoffice/risk-actions-and-investigations/).

### 5. Create a coding-agent key

1. Open `AI & Agents → Coding Agent Keys`.
2. Enter a **Label** (for example `ci-agent`; up to 200 characters) and choose scopes. The available scopes are **RUM errors**, **APM traces**, **APM errors**, **APM metrics**, **Logs**, **Profiles**, **Fingerprint / bot signals** and **KYC risk summaries**. Choose only the data the agent needs. The KYC scope covers risk summaries, not identity documents.
3. Select **Mint key** and enter your MFA code. Copy the `cak_` key; it is shown once.
4. Use **Rotate key** to replace the secret with the same scopes and label, or **Revoke key** to end access at once.

A coding-agent key is tenant-wide and read-only. The page says it never grants write access.

## Verify it works

- The assistant answers a question and lists its sources.
- The MCP token appears under **Manage** with scopes and an expiry, and **Last used** changes after your client's first call.
- Your MCP client lists tools and a call returns data inside its scopes. A call outside the scopes is refused.
- The coding-agent key row shows **Created** and, after use, **Last used**.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| No **Assistant** button | Role below Admin | Ask a workspace Admin |
| "Assistant not enabled" | Not enabled for your environment | Ask your account team |
| "Configuration pending" | No AI provider key is configured | Ask your account team, or add a provider key if you use your own |
| "You've reached the assistant's usage limit" | A usage or credit limit was reached | Wait for the reset, or ask your account team |
| "Speech input is not available for your account yet" | Speech is off or not granted | See `AI & Agents → Speech` |
| Token creation says to enter a name or choose a scope | Name under 2 characters or no scope selected | Complete the form |
| Token creation is refused for a scope | You do not hold that permission | Ask for the role that includes it |
| A plan expired | Not approved within 10 minutes | Ask the agent to plan again |
| MCP client is refused | The token is revoked, expired or out of scope | Mint a new token with the scopes the client needs |

## Related

- [AI Assistant](https://noxtica.com/docs/concepts/ai-assistant/): what the operator copilot is for.
- [MCP Integration](https://noxtica.com/docs/concepts/mcp-integration/): the external read surface.
- [MCP server](https://noxtica.com/docs/api/mcp/): endpoint, protocol and limits.
- [Integrations and API pages](https://noxtica.com/docs/backoffice/integrations/): the other credential pages.
- [Roles and permissions](https://noxtica.com/docs/security/roles-and-permissions/): the capability list.
- [Know Your Agent](https://noxtica.com/docs/concepts/know-your-agent/): incoming agents, a separate topic.

---

Source: https://noxtica.com/docs/architecture/
Markdown: https://noxtica.com/docs/architecture/index.md
Last updated: 2026-09-27

# Architecture: From Evidence to Decision

Every device tells a story. Noxtica reads the available evidence, checks whether that story holds together, and hands your application a clear, explainable risk read — not a black-box verdict. This page is the guided tour of that engine: how the browser is read, how it becomes a calibrated risk read, and where the outcome is handed back to your code. It connects the deeper implementation guides so you can follow the whole path end to end or jump straight to the stage you need.

Noxtica frames this as **Agentic Security & Risk Intelligence**, now extended for the agentic web: you can operate your own console with a built-in AI assistant, let your agents read Noxtica over a read-only MCP server, and verify and observe the agents that reach your application. See [Agentic Security & Risk Intelligence](https://noxtica.com/docs/risk-intelligence/) for that product framing; this page stays focused on the mechanics.

## The engine in four stages

| Stage | What happens | Detail |
| --- | --- | --- |
| **01. Browser** | A lightweight collector reads the visitor's browser the moment they land, without slowing the page down. | [Integration Flow → Customer client](https://noxtica.com/docs/integration-flow/#1-customer-client) |
| **02. Hand-off** | What it sees is handed safely to your backend — it cannot be faked, copied, or replayed on the way. | [Integration Flow → Noxtica processing](https://noxtica.com/docs/integration-flow/#2-noxtica-processing) |
| **03. Risk read** | Your server checks the available evidence and returns a reasoned assessment: score, five-level risk tier, confidence, and named reasons. | [Detection Signals](https://noxtica.com/docs/detection-signals/) |
| **04. Decision** | Your code makes the call — block, challenge, observe, or allow. Your policy, your context, your decision. | [Integration Flow → Customer policy](https://noxtica.com/docs/integration-flow/#4-customer-policy) |

This is a summary, not a substitute for the implementation guide: follow [Integration Flow](https://noxtica.com/docs/integration-flow/) for the full five-step evaluation checkpoint list, error handling, and rollout sequence.

## What we measure

Noxtica reads four things about every visitor — the browser, the network, the device, and how the person behaves. Together they tell a real customer apart from a clever fake; no single layer proves "human," "bot," or "safe" on its own.

- **Browser intelligence** — is this browser context internally consistent?
- **Network signals** — does the connection add risk context?
- **Device verification** — does the environment and history support the claimed context?
- **Behavioral patterns** — does eligible timing or journey context corroborate the rest?

See [Detection Signals](https://noxtica.com/docs/detection-signals/) for what each layer can contribute, its common limitations, and how to configure the evidence you need.

## What we catch

The threats that cost you — automation, fraud, and abuse — caught without false-positively challenging real customers: bots and automated traffic, sessions that hide what they are, suspicious origins, privacy users treated fairly, fake or throwaway devices, and activity that doesn't behave human. Each one gives you a risk read and a confidence level, not a blunt yes/no — your team owns the final call.

See [Threat Categories](https://noxtica.com/docs/threat-categories/) for the public reason families, their appropriate uses, and their common false-positive boundaries.

## Why a read, not a verdict

Most tools tell you what you want to hear: bot or human. Clean, simple, and often wrong, with no way to see how they got there. Noxtica separates what can be observed, what the evidence suggests, and what your business chooses to do — the useful question isn't "is this a bot," it's "how unusual is this visitor, and how hard would the suspicious parts be to fake?"

See [Why Calibration, Not Verdicts](https://noxtica.com/docs/why-calibration/) for how to turn risk and confidence into route-specific policy.

## Governing the agentic web

Three bounded, customer-controlled workflows extend this engine to AI agents, with no autonomous changes to your systems:

- **Noxtica operates the console.** A built-in AI assistant reads policies, rules, domains, and risk distribution for you under the operator session, with per-tenant budget caps and full audit logging. See [AI Assistant](https://noxtica.com/docs/concepts/ai-assistant/).
- **Your agents read Noxtica.** An opt-in, read-only Model Context Protocol (MCP) server lets your own AI agents read policies, rules, alerts, and risk distribution over JSON-RPC — read access only, never write. See [MCP Integration](https://noxtica.com/docs/concepts/mcp-integration/).
- **Noxtica governs incoming agents.** Know Your Agent (KYA) verifies and observes AI agents and bots per tenant by JWK thumbprint or Signature-Agent host, integrated with Web Bot Auth verification. Policy enforcement is on the roadmap. See [Know Your Agent](https://noxtica.com/docs/concepts/know-your-agent/).

See [Agentic Security](https://noxtica.com/docs/concepts/agentic-security/) for how these three workflows relate, and [Agentic Security & Risk Intelligence](https://noxtica.com/docs/risk-intelligence/) for the product framing that connects them to the risk read above.

## Example risk reads

Illustrative patterns derived from the threat categories above — not customer data. Scores sit on the same 0–100 scale your policy acts on.

| Pattern | Score | Verdict | Read in |
| --- | --- | --- | --- |
| Headless automation flood — a wave of headless, scripted sessions hitting login in lockstep | 94 / 100 | Blocked | 410 ms |
| Spoofed-fingerprint session — a browser lying about its own canvas output and runtime APIs | 78 / 100 | Step-up | 470 ms |
| Datacenter proxy origin — a request routed through an anonymizing datacenter range | 86 / 100 | Blocked | 350 ms |
| Privacy-browser visitor — a real person on a hardened privacy browser, waved through | 24 / 100 | Allow | 340 ms |
| Throwaway virtual machine — an emulated device posing as real consumer hardware | 90 / 100 | Blocked | 520 ms |
| Non-human interaction pattern — a form filled with tell-tale precision no person types with | 71 / 100 | Step-up | 430 ms |

## Related reading

- [Integration Flow](https://noxtica.com/docs/integration-flow/) — the full browser-to-policy evaluation, step by step.
- [Detection Signals](https://noxtica.com/docs/detection-signals/) — what each evidence layer contributes and how missing evidence affects confidence.
- [Threat Categories](https://noxtica.com/docs/threat-categories/) — public reason families and their interpretation limits.
- [Why Calibration, Not Verdicts](https://noxtica.com/docs/why-calibration/) — map risk and confidence to route-specific policy.
- [Agentic Security & Risk Intelligence](https://noxtica.com/docs/risk-intelligence/) — the product framing this engine supports.
- [Concepts & Glossary](https://noxtica.com/docs/concepts/) — agentic security, know-your-agent, MCP, and the assistant, explained.
- [Customer Capability Reference](https://noxtica.com/docs/features/) — every customer-facing capability, configuration, and limitation.

---

Source: https://noxtica.com/docs/backoffice/overview/
Markdown: https://noxtica.com/docs/backoffice/overview/index.md
Last updated: 2026-10-27

# Backoffice guide: navigation, roles and shortcuts

Backoffice is the Noxtica console at `backoffice.noxtica.com`. Use this page to learn how the sidebar is organised, which role opens which page, and which keyboard shortcuts and chrome controls save time. Operators, analysts and workspace administrators all use the same console; what you see depends on your role and on what is enabled for your organisation.

## What it is

Availability: Availability depends on your plan, role and the modules enabled for your organisation.

The left sidebar groups pages into 15 workspace groups. Each group has a heading that you can fold shut; the sidebar remembers folded groups in your browser. The top bar holds the workspace switcher (when your account belongs to more than one workspace), the command palette, notifications, page help and the UI tweaks panel. Most pages end with a **Related pages** bar, and a **Settings** menu at the top right of a page lists the settings pages that control it.

Every page is scoped to the active workspace. A role is per workspace: one account can be an Admin in one workspace and a Viewer in another.

### Roles and what they reach

| Role | What the sidebar shows |
| --- | --- |
| Viewer | Home, analytics, fingerprints and their sub-pages, Issues, RUM & APM, Behavior Analytics, Infrastructure, Pulse (when enabled), SEO pages, Usage & Quotas, Settings |
| Analyst | Everything a Viewer sees, plus Session Replay, Live Assist, Spot Captures, Hunter Reports (when enabled), Feature Flags, KYC review pages and the Audit Log |
| Admin | Everything an Analyst sees, plus every configuration page: Detection & Collection, Web Analytics & Privacy, Privacy & Legal, Integrations & API, AI & Agents, Billing & Plan, Domains, Users, Sign-in & Access, Workspace Gates, Exports and Data Operations |
| Billing | Only when enabled for your organisation: a branch role for Billing & Plan pages, not a step above Viewer |

The role you hold in the active workspace is printed in the sidebar footer. For the full capability list per role, see [Roles and permissions](https://noxtica.com/docs/security/roles-and-permissions/).

Two rules explain most "why can't I open it" questions:

- The sidebar hides a page below its minimum role. Most configuration pages are hidden below Admin. A deep link to a hidden page can still open for a lower role, but the server checks every read and every change against your role.
- A page can also be hidden or inert because a module or feature is not enabled for your organisation. Pulse, Hunter Reports and Investigations stay out of the sidebar until they are enabled. Related Devices opens with a "disabled" state when it is not enabled.

### Sidebar groups, routes and floors

Routes are paths under `backoffice.noxtica.com`. "Minimum role" is the sidebar floor.

**Overview**

| Nav label | Route | Minimum role | What you do there |
| --- | --- | --- | --- |
| Home | `/home` | Any signed-in role | See plan and usage, every product module, platform status and next steps |

**Device Intelligence.** See [Fingerprints, analytics and live monitoring](https://noxtica.com/docs/backoffice/fingerprints-and-analytics/).

| Nav label | Route | Minimum role | What you do there |
| --- | --- | --- | --- |
| Risk Analytics | `/analytics` | Viewer | Trends, distribution, signals and geography per domain |
| Traffic Intelligence | `/insights` | Admin | Read-only traffic summaries; empty until the underlying rollups are on |
| Dashboards | `/dashboards` | Viewer to read, Admin to change | Build dashboards, reusable cards and cohorts |
| Fingerprints | `/fingerprints` | Viewer | Search and open device fingerprints |
| Live Fingerprints | `/fingerprints/live-monitoring` | Viewer | Watch devices as they arrive |
| Compare Fingerprints | `/fingerprints/compare` | Viewer | Diff devices side by side |
| Fingerprint Population | `/fingerprints/population` | Viewer | Fleet-wide hardware and attestation distributions |
| Related Devices | `/fingerprints/linkage` | Viewer, when enabled | Advisory device-relation candidates |
| Geo-risk | `/geo-risk` | Admin | Risk bands per country, network and IP block |
| Hardware Attestation | `/hardware-attestation` | Admin | GPU and CPU attestation views; see [Device and app attestation](https://noxtica.com/docs/security/attestation/) |

**Session Insights.** See [Observability overview](https://noxtica.com/docs/observability/overview/).

| Nav label | Route | Minimum role | What you do there |
| --- | --- | --- | --- |
| Issues | `/issues` | Viewer | Triage grouped errors and behavior signals |
| RUM & APM (Client RUM, APM Traces, Profiles, Services, Releases, Metrics, Logs) | `/rum-apm` and `/rum-apm/<page>` | Viewer | Real-user monitoring and application performance |
| Session Replay, Live Assist | `/replay`, `/replay/live` | Analyst | Play recorded sessions and watch live ones |
| Spot Captures | `/spot` | Analyst | Review operator-started captures; see [Spot captures](https://noxtica.com/docs/hunter/spot/) |
| Hunter Reports | `/hunter-reports` | Analyst, when enabled | Review page audits; see [Hunter reports](https://noxtica.com/docs/hunter/reports/) |
| Behavior Analytics, Heatmaps, Journeys, Funnels | `/runtime-tracker` and `/runtime-tracker/<page>` | Viewer | Tracker health and behavior analytics |

**Infrastructure and Noxtica Pulse**

| Nav label | Route | Minimum role | What you do there |
| --- | --- | --- | --- |
| Infrastructure | `/infrastructure` | Viewer | Enrolled observability hosts |
| Pulse, Applications, Profiles, Bundles, Rollouts, Detections, Response, Devices, Privacy, Usage | `/pulse` and `/pulse/<page>` | Viewer to read, when enabled | Endpoint telemetry; see [Pulse overview](https://noxtica.com/docs/pulse/overview/) |

**Protection & Investigations.** See [Risk actions, investigations and entity lookup](https://noxtica.com/docs/backoffice/risk-actions-and-investigations/).

| Nav label | Route | Minimum role | What you do there |
| --- | --- | --- | --- |
| Risk Actions | `/risk-actions` | Admin | Check shadow evidence before you enforce |
| Agentic Security | `/agentic-security` | Admin | Agent verification, attestation chain and MCP usage |
| Bot Intelligence | `/bot-intel` | Admin | Named-bot catalog and operators that reached you |
| Behavioral Corroboration, Behavioral Subjects | `/behavioral`, `/behavioral/subjects` | Admin | Advisory behavioral baselines |
| Investigations | `/investigations` | Viewer, when enabled | Journey and device-location investigations |
| Entity Lookup | `/investigation` | Viewer | Look up an IP address, domain or ASN |
| Quality & Calibration | `/quality-calibration` | Admin | Calibration proposals, disputes, corpus, shadow reports |

**Identity Verification.** See [Identity verification integration](https://noxtica.com/docs/identity-verification-integration/) and [Invitations and hosted verification settings](https://noxtica.com/docs/identity-verification-invitations/).

| Nav label | Route | Minimum role | What you do there |
| --- | --- | --- | --- |
| KYC, KYC Verifications, KYC Invitations, KYC Review Queue, KYC Erasure, KYC Policies, KYC Screening Cases, KYC Rescreening, Passkeys, Step-Up Verification, Device Registry, Device Topology Policy | `/kyc` and `/kyc/<page>` | Analyst | Review verification cases and run the review workflow; administrators delete verifications in KYC Verifications and work erasure requests in KYC Erasure |
| Assisted Recovery | `/kyc/recovery` | Admin | Recovery operations queue |
| Agent Delegations | `/kyc/agent-delegations` | Analyst | See delegated agent activity |
| Evidence Access | `/kyc/evidence` | Admin | View sensitive evidence; every view is audited |
| KYB, KYM and their sub-pages | `/kyb`, `/kym` | Admin | Business and merchant verification; see [Business and merchant verification](https://noxtica.com/docs/identity-verification-business/) |

Each KYC page depends on the modules enabled for your organisation; a page whose module is off says so on the page. KYC Processes (`/kyc/processes`) has no sidebar item: open it from the KYC directory page or from a case. See [Identity verification operations](https://noxtica.com/docs/identity-verification-operations/) for the full page list.

**Detection & Collection.** See [Detection and collection settings](https://noxtica.com/docs/backoffice/detection-settings/). All pages need Admin.

| Nav label | Route | What you do there |
| --- | --- | --- |
| Rules & Risk Scoring | `/detection/rules` | Rules, simulation, risk scoring, shadow candidates |
| Client Cost Levels | `/detection/client-cost-levels` | Visitor-browser cost per domain |
| Verdict Bands | `/detection/verdict-bands` | Stage replay protection; sealed results |
| Honeypots & Shared Intel | `/detection/honeypots` | Tripwires and shared-intelligence opt-in |
| Collector | `/detection/collector` | Token refresh interval |
| Probes | `/detection/probes` | Extra collector probes |
| Behavioral Signals | `/detection/behavioral-signals` | Behavioral capture options |

**Web Analytics & Privacy and Privacy & Legal.** All pages need Admin. See [Privacy and compliance controls in Backoffice](https://noxtica.com/docs/compliance/overview/) and [Real user monitoring and Web Vitals](https://noxtica.com/docs/observability/rum/).

| Nav label | Route | What you do there |
| --- | --- | --- |
| Consent & Privacy, RUM Collection, Tracking Allowlists, Capture Policies, RUM Data Lifecycle, Uptime Checks | `/web-analytics/<page>` | Per-domain RUM consent, sampling, allowlists, capture and uptime checks |
| Data Retention, Data Locations, KYC Training Data, Compliance, Legal Basis Register, Data Subject Scope, Sub-processors, Platform Assurances | `/privacy/<page>` | Retention, legal basis and assurance pages |

**Integrations & API.** See [Integrations and API pages](https://noxtica.com/docs/backoffice/integrations/). All pages need Admin.

| Nav label | Route | What you do there |
| --- | --- | --- |
| Event Sinks | `/event-sinks` | Push events to a SIEM; see [Event sinks](https://noxtica.com/docs/backoffice/event-sinks/) |
| API & SDK | `/api-config` | Server API keys and integration links |
| MCP Tokens, Score API Keys, Ingestion API Keys, Webhooks | `/integrations/<page>` | Credentials and event delivery |
| Script & Consent | `/integrations/script-consent` | Collector snippets and consent mode |
| Alerts, Status Reports, Relay Hostnames, Attestation Apps, Connectors | `/integrations/<page>` | Notifications, reports, first-party hostnames, mobile apps, connections |

**SEO & Marketing.** Viewer reads; running checks and connecting Search Console need Admin. See [SEO tools](https://noxtica.com/docs/observability/seo-tools/).

| Nav label | Route | What you do there |
| --- | --- | --- |
| SEO Check, Site Crawls, Search Console, Search Score | `/seo/<page>` | Technical checks, crawls and search visibility for an owned domain |

**AI & Agents.** See [AI assistant, MCP tokens and coding-agent keys](https://noxtica.com/docs/backoffice/ai-assistant-and-mcp/). All pages need Admin.

| Nav label | Route | What you do there |
| --- | --- | --- |
| Agent Registry | `/ai/agent-registry` | Decide how verified AI crawlers are treated |
| LLM Routing, Speech, LLM Provider Keys | `/ai/llm-routing`, `/ai/speech`, `/ai/provider-keys` | Model routing, voice features, your own provider keys |
| Coding Agent Keys | `/integrations/coding-agent-keys` | Read-only keys for a coding agent |
| Agent Monitor | `/agent/monitor` | Watch agent runs; when enabled for your organisation |

**Billing & Plan.** See [Plans, packages and add-ons](https://noxtica.com/docs/billing/plans-and-packages/).

| Nav label | Route | Minimum role | What you do there |
| --- | --- | --- | --- |
| Usage & Quotas | `/usage` | Viewer | Meters, AI usage and spend |
| Plan | `/billing/plan` | Admin | See limits and request a change |
| Packages & Add-ons, Wallet, Invoices, Monthly Reports | `/billing/<page>` | Admin (Billing role when enabled) | Subscriptions, balance, statements and reports |

**Administration.** See [Domains, site keys and the install card](https://noxtica.com/docs/backoffice/domains/) and [Workspace gates, feature flags, data operations and mobile operations](https://noxtica.com/docs/backoffice/workspace-settings/).

| Nav label | Route | Minimum role | What you do there |
| --- | --- | --- | --- |
| Domains | `/domains` | Admin | Register origins, site keys, per-domain settings |
| Users | `/users` | Admin | Invite and manage team members; see [Roles and permissions](https://noxtica.com/docs/security/roles-and-permissions/) |
| Settings | `/settings` | Any signed-in role | Your own sign-in security, appearance, notifications |
| Sign-in & Access | `/administration/sign-in-access` | Admin | SSO, IP allowlist, enforced MFA; see [Sign-in, SSO, SCIM, MFA and IP allowlist](https://noxtica.com/docs/security/sign-in-and-access/) |
| Workspace Gates | `/administration/workspace-gates` | Admin | Optional workspace behaviours |
| Feature Flags | `/feature-flags` | Analyst to read, Admin to change | Visitor experiments |
| Mobile Operations | `/mobile-operations` | Admin | Mobile posture and the tenant kill-switch key |
| Audit Log | `/audit` | Analyst | Who changed what; see [Audit log and data export](https://noxtica.com/docs/security/audit-log-and-exports/) |
| Exports | `/exports` | Admin | Download data exports |
| Data Operations | `/data-operations` | Admin | Delete end-user browser data, retention runs |

## Prerequisites

- A Backoffice account in at least one workspace. Sign-in, SSO and MFA are covered in [Sign-in, SSO, SCIM, MFA and IP allowlist](https://noxtica.com/docs/security/sign-in-and-access/).
- An authenticator app, if you will change settings. Sensitive changes ask for a fresh MFA code (see step 5).
- For Pulse, Hunter Reports, Investigations and Related Devices: the feature enabled for your organisation. Ask your account team.

## Steps

### 1. Check your workspace and role

Look at the sidebar footer: it shows your email and role. If your account belongs to more than one workspace, the top bar also shows the workspace switcher with the active workspace name.

### 2. Switch workspace

1. Open the workspace switcher in the top bar: **Switch workspace (current: <name>)**.
2. Pick a workspace. Workspaces marked **Suspended** or **Unavailable** cannot be opened.
3. Backoffice reloads on **Home**. Nothing from the previous workspace stays on screen.

If the switch fails, the switcher shows one of three messages: you are no longer an active member, the workspace could not be verified (retry in a moment), or your network is not allowed to reach that workspace (ask its administrator to add your IP address).

### 3. Jump to a page with the command palette

Press `Ctrl+K` (`⌘K` on macOS), or use the search box at the top of the sidebar. Type at least 2 characters.

- **Navigation** lists pages you can open. Items also match aliases, for example `siem` finds Event Sinks and `mfa` finds Settings.
- **Results** lists matching entities. Everyone with device access gets device results. Users and domains need Admin. Replay sessions need the replay permission, error groups and funnels need analytics, and KYC verifications need the KYC review permission.
- **Recent pages** lists the pages you opened last while the search box is empty.

### 4. Use G shortcuts and the shortcuts list

Press `G`, then a letter within about a second.

| Keys | Opens |
| --- | --- |
| `G` `D` | Home |
| `G` `A` | Risk Analytics |
| `G` `F` | Fingerprints |
| `G` `L` | Live Fingerprints |
| `G` `C` | Compare Fingerprints |
| `G` `I` | Issues |
| `G` `R` | Session Replay |
| `G` `H` | Heatmaps |
| `G` `J` | Journeys |
| `G` `N` | Funnels |
| `G` `S` | Settings |

Press `?` to open the **Keyboard shortcuts** list. It shows only the chords your role can use. `Ctrl+\` (`⌘\` on macOS) collapses or expands the sidebar. `Esc` closes the open dialog or panel. Shortcuts stay quiet while you type in a field, while a modifier key is held and while a dialog is open.

### 5. Confirm sensitive changes with step-up MFA

Creating or rotating keys, changing domains, minting tokens, changing detection settings and similar actions ask for a code from your authenticator app, even though you are signed in. A successful check stays fresh for 6 hours by default; Backoffice asks again after that. If you cancel, nothing changes.

### 6. Set your own preferences

Open the tweaks button in the top bar (**UI tweaks**) for:

- **Theme**: Dark, Light, High contrast.
- **Density**: Compact, Comfortable, Spacious.
- **Font**: Sans, Mono, Humanist, Mixed.
- **Language**: pick a language from the list.

The same theme, density and font defaults are on **Settings → Appearance**.

### 7. Read page help and the in-console legal pages

- The help button in the top bar opens **Page help** for the page you are on, with a link to the full documentation.
- The bell opens **Notifications**: recent audit activity and destructive actions.
- The console carries read-only copies of the legal documents under `/legal/`: Terms of Service, Privacy Policy, Cookie Policy, Acceptable Use, Legal Notice, Subprocessors, Disclaimer and Data Processing Addendum. The public versions are at [Terms](https://noxtica.com/terms/), [Privacy](https://noxtica.com/privacy/), [Cookies](https://noxtica.com/cookies/), [Acceptable use](https://noxtica.com/acceptable-use/), [Legal notice](https://noxtica.com/legal-notice/), [Subprocessors](https://noxtica.com/subprocessors/), [Disclaimer](https://noxtica.com/disclaimer/) and [DPA](https://noxtica.com/dpa/).

### 8. Find a page you cannot see

| If the page is missing because | You see | Do this |
| --- | --- | --- |
| Your role is below the floor | No sidebar item; a deep link shows **Access denied** and names the required role | Ask a workspace admin for the role, or an admin to do the task |
| The module is not in your plan | A strip reading "<module> is not included in your plan" (KYC, Behavioral Corroboration, Hardware Attestation) | Ask your account team |
| The feature is not enabled for your organisation | No sidebar item (Pulse, Hunter Reports, Investigations), or a "not enabled" state on the page | Ask your account team |
| Billing needs attention | Every page except Billing & Plan and Settings is paused | See [Billing status, grace period and reminders](https://noxtica.com/docs/billing/status-grace-reminders/) |
| Your workspace requires MFA enrolment | Backoffice sends you to `/mfa/enroll` | Enrol an authenticator app |
| You are in a different workspace | The item exists in another workspace | Switch workspace (step 2) |

## Verify it works

- Press `?`: the **Keyboard shortcuts** dialog opens with an **Anywhere** section and a **Go to (press G, then the letter)** section.
- Press `Ctrl+K` or `⌘K`, type `fing`: **Fingerprints** appears under **Navigation**.
- Press `G` then `D`: Backoffice opens **Home**.
- Open the workspace switcher (if shown) and pick another workspace: the console reloads on **Home** under the new workspace name, and the role in the sidebar footer matches that workspace.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| A page in these docs is not in your sidebar | Your role is below its floor, or the feature is not enabled for your organisation | Check the role in the sidebar footer against the tables above |
| **Access denied** with "Required role: admin or higher" | The deep link needs a higher role | Ask a workspace admin |
| The palette shows no users or domains | User and domain results need Admin | Ask for the Admin role, or open the page itself |
| A `G` shortcut does nothing | Focus is in a field, a modifier key is held, a dialog is open, or the page is not available to your role | Click outside the field, close the dialog, press `G` then the letter within about a second |
| No workspace switcher | The account belongs to one workspace | None needed |
| Backoffice keeps asking for an MFA code | The fresh-verification window has passed | Enter the code; the check stays fresh for 6 hours by default |
| Every page except Billing & Plan and Settings is paused | No package is active after the grace period | Choose a package under Billing & Plan |

## Related

- [Domains, site keys and the install card](https://noxtica.com/docs/backoffice/domains/): register a domain and copy its site key.
- [Fingerprints, analytics and live monitoring](https://noxtica.com/docs/backoffice/fingerprints-and-analytics/): the Device Intelligence pages.
- [Integrations and API pages](https://noxtica.com/docs/backoffice/integrations/): map of every credential and delivery page.
- [Roles and permissions](https://noxtica.com/docs/security/roles-and-permissions/): the capability list behind each role.
- [Sign-in, SSO, SCIM, MFA and IP allowlist](https://noxtica.com/docs/security/sign-in-and-access/): MFA and SSO setup.
- [Customer Capability Reference](https://noxtica.com/docs/features/): what each capability family returns and its limits.
- [Getting started](https://noxtica.com/docs/getting-started/): install the collector and verify the evaluation.

---

Source: https://noxtica.com/docs/backoffice/fingerprints-and-analytics/
Markdown: https://noxtica.com/docs/backoffice/fingerprints-and-analytics/index.md
Last updated: 2026-10-27

# Fingerprints, analytics and live monitoring

The **Device Intelligence** group of the sidebar holds the pages for reading what the collector scored. Analysts and operators use them to find a device, understand its score, compare it with another device and see where risk concentrates. This page covers each page, what it shows and what you can do on it.

## What it is

Availability: Availability depends on your plan, role and the modules enabled for your organisation.

Every page here reads the active workspace. Results are signals for your own policy, not verdicts about a person: a fingerprint is a scored device observation, and a relation between two devices is a lead for review. See [Why calibration, not verdicts](https://noxtica.com/docs/why-calibration/).

| Page | Route | Minimum role | Use it to |
| --- | --- | --- | --- |
| Risk Analytics | `/analytics` | Viewer | Read key metrics, trends, risk distribution, signals and geography for a time range and domain |
| Traffic Intelligence | `/insights` | Admin | Read summaries of bot-versus-human share, AI-crawler traffic, geography against risk and anomalies; observe-only |
| Dashboards | `/dashboards` | Viewer to read, Admin to change | Build dashboards, reusable cards and cohort analyses |
| Fingerprints | `/fingerprints` | Viewer | Search, filter and open real device records |
| Live Fingerprints | `/fingerprints/live-monitoring` | Viewer | Watch devices arrive in near real time |
| Compare Fingerprints | `/fingerprints/compare` | Viewer | Diff up to four devices |
| Fingerprint Population | `/fingerprints/population` | Viewer | Read fleet-wide hardware and attestation distributions |
| Related Devices | `/fingerprints/linkage` | Viewer, when enabled | Review advisory candidate relations between devices |
| Geo-risk | `/geo-risk` | Admin | See risk bands per country, network (ASN) and IP block |
| Hardware Attestation | `/hardware-attestation` | Admin | Read GPU and CPU attestation distributions, GPU detail and mobile attestations |
| Issues | `/issues` | Viewer | Triage grouped errors and behavior signals |

Some pages show an empty or "not enabled" state until the underlying rollup or module is turned on for your organisation. An empty state is not evidence of no traffic.

## Prerequisites

- A workspace with at least one registered domain that sends traffic. See [Domains, site keys and the install card](https://noxtica.com/docs/backoffice/domains/).
- The minimum role in the table. Roles are explained in [Backoffice guide](https://noxtica.com/docs/backoffice/overview/).
- For Hardware Attestation: the attestation module in your plan and attestation enabled for the domain. See [Device and app attestation](https://noxtica.com/docs/security/attestation/).
- For Related Devices: the feature enabled for your organisation and a recorded legal basis for investigations. Without them the page opens with a disabled state.

## Steps

### 1. Find a device in Fingerprints

Open `Backoffice → Device Intelligence → Fingerprints`.

- **Search** accepts a device ID, IP address, ASN or user-agent text.
- Filters cover **Risk** (Critical, High, Medium, Low, Minimal, Unknown), **Country**, the collection **Method** (native, sealed, sealed with encryption) and **Hardware Attestation** (attested or not attested).
- The **Devices** tab lists devices. The **User Agents** tab lists each distinct user-agent string with counts and a copy action.
- The list refreshes itself every 5, 15 or 30 seconds. Use **Pause** and **Resume**, or **Refresh**.
- Pick the page size from 25, 50 or 100 rows. Selections persist across pages and filter changes.
- Tick 2 to 4 rows and choose **Compare**, or choose **Export** to open `Exports` with your current filters filled in. Exports are described in [Audit log and data export](https://noxtica.com/docs/security/audit-log-and-exports/).

### 2. Read a device record

Select a row. The record opens at `/fingerprints/<device id>` with tabs:

| Tab | What it shows |
| --- | --- |
| Overview | Score, risk band, confidence, flags, and a ranked "Why this score" breakdown with no personal data |
| Sessions timeline | Replay sessions captured for this device in the last 90 days that are still within replay retention (7 days by default), newest first; plus a 7-day activity strip of visits, submissions and risk signals (dates in UTC) |
| Browser, Network, Hardware | Collected browser, network and hardware signals |
| Behavioral | Behavioral subscore and signals, when collected |
| Techniques | Which collection techniques were switched on for this submission |
| Population | Where this device sits in your fleet distributions |
| Events | Event timeline for the device |
| History | Prior scores |
| Raw | The raw submission; visible to platform superadmins only |

Header actions include **Copy ID**, **Compare**, **View journeys**, **View heatmap**, **View in Investigations** (when enabled) and **Open in…**. When disputes are enabled for your workspace, the Overview tab offers **Dispute Verdict** to open a false-positive dispute; the dispute goes to the review workflow described in [Risk actions, investigations and entity lookup](https://noxtica.com/docs/backoffice/risk-actions-and-investigations/). The sessions timeline says "One device only": it does not merge identities.

### 3. Watch live traffic

Open `Device Intelligence → Live Fingerprints`. The page streams recent visits and submissions with a location map.

- KPI tiles: **Active devices**, **Active now**, **Devices seen (history)**, **Visits**, **Submissions**, **High / Critical**.
- **Filter the stream by risk level**, pause and resume it, and choose a polling interval of 5, 15 or 30 seconds.
- Select a row to open the device record.
- The history panels can lag. The page states the lag: history up to the shown window, which "may lag up to ~15 min". If the real-time read fails, the page says so and shows delayed history instead.

### 4. Compare devices

Select 2 to 4 rows on Fingerprints and choose **Compare**, or open `/fingerprints/compare?ids=<a>,<b>`. Tabs: **Overview**, **Signals**, **Signal data**, **Environment**, **Raw**. Differences are highlighted; flags are split into common and only-in-one-device. If a device ID exists in more than one workspace you can reach, pick the tenant for each slot.

### 5. Read population statistics

Open `Fingerprint Population` for fleet-wide distributions over a window of 24 hours, 7 days or 30 days, filtered by signal family. Buckets with too few devices are hidden before they reach the page, and hidden buckets are excluded from every total. The page never identifies an individual device and changes no detection behavior. Use a device's **Population** tab to see where one device sits.

### 6. Review Related Devices (when enabled)

`Related Devices` lists candidate relations: two device IDs that share signals, with a confidence (High, Medium, Low), an ordinal score from 0 to 100 for ranking, the link types and the itemised evidence and counter-evidence. A relation expires. It never merges devices and never feeds a score or verdict. The page states that edge precision and 7-day re-link recall have not been evaluated, so treat each relation as a lead, not as proof that one operator controls both devices.

### 7. Use Risk Analytics and Dashboards

`Risk Analytics` has the tabs **Trends**, **Distribution**, **Signals** and **Geography**, a **Time range**, a **Breakdown dimension** (Country, City, Platform, ASN) and key figures: **Total submissions**, **Critical rate**, **High risk** and a device count. Use **CSV** buttons to download a chart's data. **Views → Save current view…** stores the time range, filters and toggles as a preset that only you can see.

`Dashboards` has the tabs **Dashboards**, **Cards** and **Cohorts**. Build operator views from funnels, journeys, heat maps, web vitals, dimensions, retention and feature adoption. Viewers and Analysts read them. Creating or changing a dashboard, card or cohort needs the Admin role and a fresh MFA check.

### 8. Read Geo-risk and Hardware Attestation

- `Geo-risk` (Admin) has the tabs **Country**, **ASN** and **IP block** over 7, 30 or 90 days, with a map. Cells below the privacy floor are suppressed. Without the underlying rollup the page says "Not enabled yet".
- `Hardware Attestation` (Admin) has **Distribution**, **GPU detail** and **Mobile attestations**. The mobile tab is a read-only ledger of Android and iOS attestation results for the workspace, with Play Integrity and App Attest verdicts shown as recorded. If too few records exist, the ledger hides individual rows. Register your apps under `Integrations & API → Attestation Apps`; see [Device and app attestation](https://noxtica.com/docs/security/attestation/).

### 9. Triage Issues

`Issues` groups runtime errors and deterministic behavior signals. The **Errors** and **Behavior** tabs take filters for severity, type, route, release and device. Severity is a deterministic impact rule: occurrences multiplied by affected users (1,000 or more is Critical, 100 or more High, 10 or more Medium, otherwise Low), with a High floor on checkout, payment and billing routes. It is not AI grading. Error capture is covered in [Browser errors, console logs and source maps](https://noxtica.com/docs/observability/errors-and-source-maps/).

## Verify it works

- A device you know sent traffic appears on **Fingerprints** after a search by its device ID, and its record opens with a score, a band and the **Why this score** breakdown.
- **Live Fingerprints** shows **Streaming** and your visit appears within one polling interval.
- On a comparison, selected devices show a difference count and highlighted rows.
- **Risk Analytics → Trends** shows non-zero **Total submissions** for the chosen range.
- If a page shows "not enabled", "Rollup disabled" or an empty table, widen the range and confirm traffic exists before you conclude anything.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| Fingerprints is empty | No traffic yet, a filter is narrowing the list, or the domain's collector is not installed | Select **Clear filters**; check **Last seen** on Domains |
| Live Fingerprints shows "Real-time read unavailable" | The real-time read failed; delayed history is shown instead | Retry; history panels are unaffected |
| **Raw** tab is missing | The raw submission is visible to superadmins only | Use the other tabs |
| Compare asks you to pick a tenant | The device ID exists in more than one workspace | Choose the tenant for that slot |
| Population or Geo-risk hide a bucket | The bucket is below the privacy floor | Widen the window; a hidden bucket is not a zero |
| Geo-risk shows "Not enabled yet" | The rollup is not enabled for your organisation | Ask your account team |
| Related Devices shows a disabled state | Feature or investigation legal basis is not in place | Ask your account team; see [Legal basis register and receipts](https://noxtica.com/docs/compliance/legal-basis/) |
| Hardware Attestation tabs are empty | Attestation is not enabled for the domain, or no attested traffic has arrived yet | See [Device and app attestation](https://noxtica.com/docs/security/attestation/) |
| A dashboard or card will not save | Changes need the Admin role and an MFA check | Enter the authenticator code |

## Related

- [Backoffice guide: navigation, roles and shortcuts](https://noxtica.com/docs/backoffice/overview/): roles and shortcuts, including `G F`, `G L` and `G C`.
- [Risk actions, investigations and entity lookup](https://noxtica.com/docs/backoffice/risk-actions-and-investigations/): act on what you find.
- [Detection signals](https://noxtica.com/docs/detection-signals/): what each evidence layer contributes.
- [Threat categories](https://noxtica.com/docs/threat-categories/): public reason families and false-positive boundaries.
- [Behavior analytics: heatmaps, journeys and funnels](https://noxtica.com/docs/observability/behavior-analytics/): the tracker pages.
- [Audit log and data export](https://noxtica.com/docs/security/audit-log-and-exports/): export fingerprints and events.

---

Source: https://noxtica.com/docs/backoffice/risk-actions-and-investigations/
Markdown: https://noxtica.com/docs/backoffice/risk-actions-and-investigations/index.md
Last updated: 2026-10-27

# Risk actions, investigations and entity lookup

The **Protection & Investigations** group of the sidebar is where you check what your policy would do, review agent and bot traffic, and investigate a lead. Admins validate risk actions here before they move enforcement from shadow to active. Analysts use the lookup and investigation pages to follow a lead across devices and networks.

## What it is

Availability: Availability depends on your plan, role and the modules enabled for your organisation.

Most pages in this group show evidence. They do not act on traffic. The table says which pages are observe-only and which carry a change you can make.

| Page | Route | Minimum role | Observe-only or actionable |
| --- | --- | --- | --- |
| Risk Actions | `/risk-actions` | Admin | Observe-only: shows what the pipeline would have done |
| Agentic Security | `/agentic-security` | Admin | Observe-only: agent verdicts, attestation chain and MCP usage |
| Bot Intelligence | `/bot-intel` | Admin | Observe-only: catalog and activity |
| Behavioral Corroboration, Behavioral Subjects | `/behavioral`, `/behavioral/subjects` | Admin | Advisory; one action: reset a subject baseline (MFA and confirmation) |
| Investigations | `/investigations` | Viewer, when enabled | Read-only views and saved views; no case actions |
| Entity Lookup | `/investigation` | Viewer | Lookups; sanctions screening is advisory |
| Quality & Calibration | `/quality-calibration` | Admin | Actionable: accept or reject calibration proposals, open and resolve disputes, import labels |

Results are signals for your own decision. A sanctions-screening match, a behavioral deviation or a bot-operator match is a lead for human review, never an automatic block. See [Why calibration, not verdicts](https://noxtica.com/docs/why-calibration/).

Enforcement itself is configured under **Detection & Collection → Rules & Risk Scoring**. See [Detection and collection settings](https://noxtica.com/docs/backoffice/detection-settings/).

## Prerequisites

- The minimum role from the table. Roles are explained in [Backoffice guide](https://noxtica.com/docs/backoffice/overview/).
- For Investigations: the feature enabled for your organisation and an active legal-basis receipt. Without them the page opens with an "Investigations not enabled" state, and the sidebar item stays hidden. See [Legal basis register and receipts](https://noxtica.com/docs/compliance/legal-basis/).
- For Entity Lookup enrichment: OSINT enrichment enabled for your organisation. Without it a lookup shows "Enrichment not enabled".
- For Behavioral Corroboration: the behavioral module in your plan. Without it a strip reads "Behavioral Corroboration is not included in your plan".
- An authenticator app. Accepting a calibration proposal and resetting a behavioral baseline ask for a fresh MFA code.

## Steps

### 1. Validate risk actions before you enforce

Open `Backoffice → Protection & Investigations → Risk Actions`. The page states: "Everything here is what the pipeline WOULD have done. No policy is enforced from this page."

- **Shadow decisions** count would-be policy actions. **Submit shadow hits** are per-submission decisions. **Enforcement shadow hits** are in-path allow, challenge or block decisions made while enforcement runs in shadow. Counts are approximate volumes.
- **Challenge outcomes by method** break down **Invisible PoW** and **Turnstile** step-up challenges into **Issued**, **Solved**, **Failed** and **Abandoned**. **Challenge solve rate** is solved divided by solved plus failed.
- Submit and enforcement counts cover the last 24 rolling hours. Challenge outcomes cover the current UTC day. The two windows rarely align, so a later stage can show a higher count than an earlier one.
- **Live updates** polls for new data. Use **Refresh** to reload.

A tenant admin sees only the own workspace. If the page says "Risk Actions not provisioned", the shadow pipeline has no data yet; it is off until it is enabled for your workspace.

### 2. Review agent traffic in Agentic Security

Open `Agentic Security`. It is read-only and has three sections:

- **Agent verification verdicts**: **Verified**, **Unsigned**, **Invalid signature**, **Expired** and **Replay** over 24 hours, 7 days or 30 days.
- **Attestation-chain forensics**: per-agent observations recorded in shadow. Detail is hidden below a small-count threshold and only a summary shows.
- **MCP token usage**: queries used, period limit and remaining for the current period.

A **Cloudflare Verified AI Agents** panel can seed the agent registry when your deployment exposes it. Each section shows its own "not enabled" note until its rollup is on. Concepts are in [Know Your Agent](https://noxtica.com/docs/concepts/know-your-agent/) and [Agentic Security](https://noxtica.com/docs/concepts/agentic-security/).

### 3. Browse bot operators in Bot Intelligence

`Bot Intelligence` shows a **Verified bot catalog** of named operators, with source and license attribution, and **Per-operator activity** for your workspace over 1, 7 or 30 days. Filter the catalog by operator, slug, category or kind. The catalog is platform data; the activity is yours. Empty states distinguish "not enabled", "waiting for upstream collection" and "no recognized bot activity in this window".

### 4. Read behavioral corroboration

`Behavioral Corroboration` shows the enrolment funnel (learning to active), the session-deviation histogram, drift by capture channel and concordance against labeled ground truth. `Behavioral Subjects` lists pseudonymous subjects with status, sample count, last deviation band (low through severe) and drift time. A deviation says how consistent a session is with the subject's own history. It is advisory evidence, never identity and never a verdict. Small groups are suppressed. On a subject page you can reset the baseline, which returns it to learning and clears learned statistics; that needs a fresh MFA check and a confirmation.

### 5. Investigate (when enabled)

`Investigations` has five tabs: **Journeys (Sankey)**, **Device Locations**, **Journeys (Chord)**, **Events** and **Incident Triage**.

- **Events** takes filters for risk, attestation, automation, network and account. Select **Apply**, then page with **Load more**; **Download CSV** exports the loaded rows.
- **Journeys (Chord)** shows how devices, accounts, agents and networks co-occur. Pairs below a privacy floor of 5 are not shown.
- **Incident Triage** is read-only: status counts and grouping of existing signals, with no case queue and no close actions.
- Save a view with the saved-views menu. Superadmins must pick a workspace first.

Reads are tenant-scoped. When the feature or the legal-basis receipt is missing, each tab shows a disabled state.

### 6. Look up an entity

Open `Entity Lookup`, enter an IP address, domain or ASN (for example `8.8.8.8`, `example.com`, `AS13335`) and select **Investigate**. Enrichment tabs include **IP**, **WHOIS / RDAP**, **BGP / ASN**, **DNS**, **Certificates**, **Threat intel**, **CVE (NVD)** and **GitHub**. An **Entity graph** expands related entities. A separate sanctions search screens a name against the US OFAC Specially Designated Nationals list. The page says it is advisory, does not claim to be complete, and a match is "a lead for human review — never an automated block or decision". Source attribution is listed under the results.

### 7. Work the calibration queue

`Quality & Calibration` has five tabs: **Calibration inbox** (default), **Calibration concordance**, **FP disputes**, **Corpus** and **Shadow reports**.

| Tab | What you do | Notes |
| --- | --- | --- |
| Calibration inbox | Review proposals (Proposed, Accepted, Rejected); inspect the threshold change and its evidence; accept or reject | Propose-only. Nothing applies until you accept, and accepting needs a fresh MFA check. Each proposal shows its origin and whether AI drafted it |
| Calibration concordance | Read how each shadow candidate would change bands over a window | Read-only; never applies a change |
| FP disputes | Open, track and resolve false-positive disputes; export the list to CSV | A dispute moves from open through reviewing to upheld or overturned. Resolving is an admin action |
| Corpus | Read the labeled bot or human base rate; import labels from resolved disputes or add a manual label | A label is annotation only and never moves a scoring weight. Import and annotate need MFA |
| Shadow reports | Read a per-flag report card for each shadow signal over 24 hours, 7 days or 30 days | Recommendations are annotations. Weight changes stay a separate, explicit step |

You can also open a dispute from the **Dispute Verdict** button on a device record. See [Fingerprints, analytics and live monitoring](https://noxtica.com/docs/backoffice/fingerprints-and-analytics/).

## Verify it works

- **Risk Actions** shows non-zero shadow counts after traffic has been evaluated, or a clear "no risk-action evidence in this window" state.
- **Agentic Security** shows a verdict total for the window you pick, or a note naming the rollup that is off.
- **Entity Lookup** returns tabs of results for a valid IP, domain or ASN, or "Enrichment not enabled".
- A calibration proposal you accept appears under **Accepted** after the MFA check.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| Risk Actions says "not provisioned" | The shadow pipeline and challenge ladder are off by default | Ask your account team; collect traffic after enablement |
| Counts at a later stage exceed an earlier one | Submit counts use 24 rolling hours, challenge outcomes the UTC day | Compare within one window only |
| Investigations is not in the sidebar | Feature or legal-basis receipt is not enabled | Ask your account team |
| Entity Lookup says "Enrichment not enabled" | OSINT enrichment is off for your organisation | Ask your account team |
| Bot Intelligence is empty | Named-operator collection is not enabled, or no recognized bots arrived in the window | Widen the window; ask your account team |
| Behavioral pages are empty | No subjects have enrolled | Review the behavioral settings in [Detection and collection settings](https://noxtica.com/docs/backoffice/detection-settings/) |
| Sanctions screening is rate limited | Too many screenings in a short time | Wait a moment and retry |
| Accepting a proposal fails | The MFA check lapsed | Enter a new authenticator code |

## Related

- [Detection and collection settings](https://noxtica.com/docs/backoffice/detection-settings/): enforcement mode, risk scoring and shadow candidates.
- [Fingerprints, analytics and live monitoring](https://noxtica.com/docs/backoffice/fingerprints-and-analytics/): devices and population context.
- [Know Your Agent](https://noxtica.com/docs/concepts/know-your-agent/): how incoming agents are evaluated.
- [Calibration](https://noxtica.com/docs/concepts/calibration/): how to read risk and confidence.
- [Threat categories](https://noxtica.com/docs/threat-categories/): public reason families.
- [Roles and permissions](https://noxtica.com/docs/security/roles-and-permissions/): the capabilities behind each page.

---

Source: https://noxtica.com/docs/backoffice/detection-settings/
Markdown: https://noxtica.com/docs/backoffice/detection-settings/index.md
Last updated: 2026-10-27

# Detection and collection settings

The **Detection & Collection** group holds seven pages that change how Noxtica scores traffic and what the collector asks of a visitor's browser. A workspace Admin changes them. This page says what each setting changes and gives an order for rolling a change out so that live traffic is never surprised.

## What it is

Availability: Availability depends on your plan, role and the modules enabled for your organisation.

All seven pages are Admin pages in the sidebar. Every change is audited and asks for a fresh MFA check. Several settings have two keys: your switch, and a platform switch that Noxtica operations controls. Turning on your key does nothing visible until the platform key is also on, and a page says so next to the switch.

| Page | Route | What it changes |
| --- | --- | --- |
| Rules & Risk Scoring | `/detection/rules` | Ordered enforcement rules, the stage of enforcement, signal weights, risk-level cutoffs, shadow candidates |
| Client Cost Levels | `/detection/client-cost-levels` | How much work a visitor's browser does, per domain |
| Verdict Bands | `/detection/verdict-bands` | Staging of replay protection and binding; sealed results |
| Honeypots & Shared Intel | `/detection/honeypots` | Decoy tripwires; contribution to and use of shared intelligence |
| Collector | `/detection/collector` | Session-token refresh interval |
| Probes | `/detection/probes` | DNS-leak, extension, location and device-recognition probes |
| Behavioral Signals | `/detection/behavioral-signals` | Behavioral capture, movement tracks and behavior flags |

Several of these settings read personal data from visitors' browsers. Noxtica provides the mechanism; the legal basis is yours. Link your decisions to [Legal basis register and receipts](https://noxtica.com/docs/compliance/legal-basis/) and [Cookies, storage and consent categories for your site](https://noxtica.com/docs/compliance/cookies-and-storage/).

## Prerequisites

- The Admin role in the workspace. See [Backoffice guide](https://noxtica.com/docs/backoffice/overview/).
- An authenticator app for the step-up check.
- At least one domain with traffic, so shadow evidence can accumulate. See [Domains, site keys and the install card](https://noxtica.com/docs/backoffice/domains/).
- For behavioral capture, movement tracks, the extension probe, the location probe and persistent device recognition: counsel review and end-user consent where the law requires it. The page shows a warning next to each switch.

## Steps

### 1. Plan the rollout order

Change one thing at a time and watch the evidence before the next change.

1. Collection cost first: **Client Cost Levels** and **Collector** change load, not decisions.
2. Collection additions next: **Probes** and **Behavioral Signals**, each with a recorded legal basis.
3. Scoring: **Risk scoring** weights and cutoffs, tested with **Shadow candidates** and **Simulate & evidence** before you save.
4. Enforcement: write **Rules**, set **Enforcement mode** to **Shadow**, read [Risk actions, investigations and entity lookup](https://noxtica.com/docs/backoffice/risk-actions-and-investigations/), and only then consider **Active**.
5. Protection bands: move **Verdict Bands** from off to shadow, observe, then active.

### 2. Write rules and set the enforcement stage

Open `Detection & Collection → Rules & Risk Scoring`. The page has four tabs: **Rules**, **Simulate & evidence**, **Risk scoring** and **Shadow candidates**.

- **Rules** is an ordered list. Rules run by ascending priority, and the earliest matching rule picks the action. Actions are **Allow**, **Challenge**, **Block** and **Tarpit**. A rule can match on risk band, fired flags, agent verdict, URL path, device score, device properties, IP reputation or a flag prefix, and a per-rule challenge method (**Invisible proof-of-work** or **Turnstile**). A workspace can hold up to 100 rules.
- **Enforcement mode** has three stages. **Off** forwards every request. **Shadow** evaluates your rules and logs the would-be action without acting; this is the recommended first stage. **Active** acts on matches: block, challenge or tarpit. Changing the mode needs MFA, and switching to Active asks you to confirm.
- A rule acts only when the mode is Active and the rule's own **Shadow** switch is off. Otherwise it observes. Each rule shows "Observing" or "Enforcing" with the reason.
- Selecting Active also depends on a platform enforcement switch that Noxtica operations controls. You can stage Active in advance, and it takes effect when that switch is on.
- **Simulate & evidence** dry-runs a rule against recent events and shows the daily fire mix, so you can size a rule before you arm it.
- **Revisions & rollback** publishes the live rule set as a numbered revision and can roll back to an older one. History is never rewritten.
- Domain-scoped rules are also available on a domain's **Risk rules** tab and apply alongside tenant-wide rules.

### 3. Tune risk scoring

On the **Risk scoring** tab you can change the weight of each signal and the four cutoffs that map a score to a risk band. Cutoffs must stay strictly ordered: Critical above High above Medium above Low. A signal you turn off is ignored. High-confidence bot signals are marked **Critical signal** and only a platform superadmin can change or disable them. **Estimate impact** previews how a change would shift the band mix over recent traffic without applying it. **Reset to defaults** clears your overrides.

On the **Shadow candidates** tab, author alternative weightings. A candidate runs in a shadow pass, records a delta against the production verdict for the concordance view, and never changes a live verdict. Use **Traffic impact** to estimate flips. Accepting a change into production is a separate, deliberate step in [Risk actions, investigations and entity lookup](https://noxtica.com/docs/backoffice/risk-actions-and-investigations/).

### 4. Set Client Cost Levels

Open `Client Cost Levels`, pick a domain, and choose **Off**, **Light**, **Standard** or **High** for each of three costs:

| Cost | What it controls |
| --- | --- |
| Proof-of-work & challenge cost | How deep the CPU and GPU proof-of-work ladder runs, and whether the challenge prefers proof-of-work over Turnstile. Off skips proof-of-work |
| Detection probes cost | Which client-side probes run. Off disables every probe on the domain |
| Session-replay capture cost | Replay sampling, throttling and network-body capture. Saving any level needs an active session-replay legal-basis receipt |

Standard is the default behavior. Higher levels detect more and ask more of every visitor's device. The page suggests Light for checkout flows. The cost lands on the visitor's device, so no level needs extra sign-off. Any effective replay rate below 100 percent records no anonymous web visitors.

### 5. Stage Verdict Bands and sealed results

`Verdict Bands` has two sections.

- **Sealed Runtime security bands**: **Replay protection mode** and **Binding mode**. Each moves **Off → Shadow → Active**. Off and shadow do not enforce. Active becomes selectable once a band is in shadow. In Active the replay band can block live submissions, subject to the platform enforcement switch. The binding band is signal-only in this iteration: Active does not block.
- **Sealed results**: turn on **Emit sealed results** and the submit response carries an encrypted envelope that only your backend can open. It restores the detailed flags withheld from the browser response. Your server fetches the key with a secret API key that carries the `read:sealed_results` scope, then opens the envelope. The console never shows the key. See the [Server API overview](https://noxtica.com/docs/api/).

### 6. Honeypots and shared intelligence

On `Honeypots & Shared Intel`, **Enable honeypot tripwires** arms decoy routes, decoy form fields and per-session canary tripwires. A tripped wire raises a risk signal for your rules and never blocks a visitor on its own. The page shows anonymous daily counts per tripwire (**Hits (7d)**). **Rotate canary** invalidates current per-session canaries and needs MFA. Detection stays inactive until the platform also arms honeypots for your workspace.

**Federated intelligence** has two independent switches: **Contribute** reports an anonymized, tenant-blinded marker when a cluster escalates; **Consume** lets scoring read a shared signal that exists only after several workspaces flagged the same cluster. Both default to off.

### 7. Set the Collector refresh interval

On `Collector`, **Token refresh interval** controls how often the script refreshes its session token. Options: 30 seconds, 1 minute, **5 minutes (default)**, 15 minutes, 1 hour, 6 hours, 24 hours, or **Use plan default**. Your plan sets a floor; a value below it is refused. Lower values are more responsive and cost more infrastructure. **Effective** shows the value in force. A single domain can override the interval on its detail page. New sessions use the new interval.

### 8. Toggle probes and behavioral signals

`Probes` has four sections. Each is a switch with a warning.

| Probe | What it does | Notes |
| --- | --- | --- |
| DNS-leak probe | Compares the observed DNS resolver with the client network | Default off. Needs the platform switch as a second key |
| Extension probe | Probes a short list of high-signal browser extensions; stores a one-way hash and a count, not the list | On Chromium browsers it causes one expected console error line per page view. Never used to auto-block |
| Geo probe | Reads precise location only when the browser has already granted permission; never prompts | Only a coarse bucket is emitted |
| Persistent device recognition | Recognizes a returning device with a daily-rotating token keyed to a clearable first-party ID | Off by default. The page calls it the most legally sensitive setting. Recognition only; never used to auto-block |

`Behavioral Signals` has three sections: **Behavioral biometrics** (mouse, click and scroll patterns for a per-domain behavioral subscore; disabled by default and classified as biometric data under the GDPR), **Behavioral path tracks** (a higher-risk category: pointer and touch path geometry; turning it off permanently deletes stored path records), and **Behavioral flags** (server-derived flags from session aggregates such as no interaction; default off, with a platform switch as the second key).

## Verify it works

- After saving, the page shows a success message and the **Last changed** time.
- After you set a rule to shadow, the rule card reads "Observing (shadow)" and **Would have fired** counts grow with traffic.
- **Effective** on the Collector page shows the interval you chose.
- A verdict band set to Shadow shows no blocking; check Risk Actions for would-be decisions.
- Every change appears in the [audit log](https://noxtica.com/docs/security/audit-log-and-exports/).

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| Switch is on but nothing changes | The platform key for that feature is off | Ask your account team to confirm the platform switch |
| **Active** is greyed out for a band | The band is Off | Move it to Shadow first and observe |
| Rules log matches but do not act | Mode is Off or Shadow, or the rule's Shadow switch is on | Set mode to Active and turn off the rule's Shadow switch when evidence supports it |
| Thresholds will not save | Cutoffs are not strictly ordered | Keep Critical above High above Medium above Low |
| A signal cannot be changed | It is a critical signal | Only a platform superadmin can change it |
| Cost level will not save for replay | No active session-replay legal-basis receipt | Record one under Web Analytics & Privacy → Capture Policies |
| Interval below plan floor | The plan sets a minimum | Choose a larger value or **Use plan default** |
| Adding a rule fails with "Rules are limited to 100 per tenant" | The workspace holds 100 rules | Delete or merge rules |

## Related

- [Risk actions, investigations and entity lookup](https://noxtica.com/docs/backoffice/risk-actions-and-investigations/): read shadow evidence before you go Active.
- [Domains, site keys and the install card](https://noxtica.com/docs/backoffice/domains/): per-domain tracker policy and token refresh.
- [Consent modes, GPC and Google Consent Mode](https://noxtica.com/docs/sdk/consent/): what the browser does without consent.
- [Protected actions: client trigger and server check](https://noxtica.com/docs/sdk/protected-actions/): protect login and checkout.
- [Why calibration, not verdicts](https://noxtica.com/docs/why-calibration/): map risk and confidence to your policy.
- [Legal basis register and receipts](https://noxtica.com/docs/compliance/legal-basis/): record the basis for optional collection.

---

Source: https://noxtica.com/docs/backoffice/integrations/
Markdown: https://noxtica.com/docs/backoffice/integrations/index.md
Last updated: 2026-10-27

# Integrations and API pages

The **Integrations & API** group of the Backoffice sidebar holds every page that connects Noxtica to your code and your tools: credentials, install snippets, event delivery, notifications and connections. A workspace Admin uses these pages. This page maps each one, so you know where to go and which guide covers the detail.

## What it is

Availability: Availability depends on your plan, role and the modules enabled for your organisation.

The group has 11 sidebar pages, all Admin in the sidebar. A twelfth credential page, **Coding Agent Keys**, sits in **AI & Agents** and is covered in [AI assistant, MCP tokens and coding-agent keys](https://noxtica.com/docs/backoffice/ai-assistant-and-mcp/).

| Nav label | Route | What it does | Covered in |
| --- | --- | --- | --- |
| Event Sinks | `/event-sinks` | Push verdict and audit events to a SIEM | [Event sinks](https://noxtica.com/docs/backoffice/event-sinks/) |
| API & SDK | `/api-config` | Server API keys and integration links | [Server API](https://noxtica.com/docs/api/), [Authentication](https://noxtica.com/docs/api/authentication/) |
| MCP Tokens | `/integrations/mcp-tokens` | Read-only tokens for an MCP client | [AI assistant, MCP tokens and coding-agent keys](https://noxtica.com/docs/backoffice/ai-assistant-and-mcp/), [MCP server](https://noxtica.com/docs/api/mcp/) |
| Score API Keys | `/integrations/score-api-keys` | Keys for server-side score calls | [Backend Integration](https://noxtica.com/docs/backend-integration/) |
| Script & Consent | `/integrations/script-consent` | Collector snippets, consent mode, protected actions | [Install & Browser Runtime](https://noxtica.com/docs/browser-runtime/) |
| Ingestion API Keys | `/integrations/ingestion-api-keys` | Keys for traces, metrics and logs | [APM and the ingestion service](https://noxtica.com/docs/observability/apm-and-ingest/) |
| Webhooks | `/integrations/webhooks` | Signed event delivery to your HTTPS endpoints | [Webhooks](https://noxtica.com/docs/api/webhooks/) |
| Alerts | `/integrations/alerts` | Email, Slack or webhook alerts | [Uptime checks, alerts, status reports](https://noxtica.com/docs/observability/uptime-alerts-status/) |
| Status Reports | `/integrations/status-reports` | Periodic email reports | [Uptime checks, alerts, status reports](https://noxtica.com/docs/observability/uptime-alerts-status/) |
| Relay Hostnames | `/integrations/relay` | Serve the collector from your own hostname | [Content Security Policy, hosts and first-party relay](https://noxtica.com/docs/sdk/csp-and-relay/) |
| Attestation Apps | `/integrations/attestation-apps` | Register Android and iOS apps | [Device and app attestation](https://noxtica.com/docs/security/attestation/) |
| Connectors | `/integrations/connectors` | Connect log providers, issue trackers, help desks and warehouses | This page |

The sidebar label for the server key page is **API & SDK**. Some older pages call it "API Config"; its page heading reads **API Configuration**.

## Prerequisites

- The Admin role. Lower roles do not see these pages, and the server checks the role on every read and every change. See [Backoffice guide](https://noxtica.com/docs/backoffice/overview/).
- An authenticator app. Creating, rotating and revoking a credential asks for a fresh MFA check.
- A place to store a secret. Every credential is shown once, when you create it. Backoffice cannot show it again.
- Some pages exist but depend on your plan or on a feature being enabled for your organisation, for example Score API Keys and Alerts. A page that is not available shows an empty or "not enabled" state, or a 404 on its API.

## Steps

### 1. Create a server API key (API & SDK)

1. Open `Backoffice → Integrations & API → API & SDK`. The tabs are **Client Integration**, **Backend Integration** and **Server API Keys**.
2. On **Server API Keys** select **Create API Key**.
3. Enter a **Key Name** (required), choose the narrowest **Scopes**, and select **Create Key**. The picker groups scopes as **Read access**, **Write access** and **Erase (destructive)**. A new key starts with `read:device` selected.
4. Copy the **Secret Key**. The page says "Save this secret key now — it will not be shown again."
5. To replace a key, select **Rotate** and type `ROTATE`. To retire it, select **Revoke** and type `REVOKE`. Revoking is permanent and requests that use the key fail at once.

Server keys start `sk_prod_`. Never put a secret key in browser code. Scope meanings, errors and limits are in [Server API](https://noxtica.com/docs/api/), [Authentication](https://noxtica.com/docs/api/authentication/) and [Errors](https://noxtica.com/docs/api/errors/).

### 2. Install the collector (Script & Consent)

Open `Script & Consent`. Tabs: **How it works**, **Snippets**, **Consent & extensions**, **Protected actions**, **CSP & storage**, **Check it works**. Pick a domain (the page keeps it in the URL as `?domain_id=`), copy its core script, choose how the domain receives consent, and name protected actions such as login or checkout. The public walkthrough is [Install & Browser Runtime](https://noxtica.com/docs/browser-runtime/). See also [Domains, site keys and the install card](https://noxtica.com/docs/backoffice/domains/).

### 3. Add a webhook

1. Open `Webhooks`. Tabs: **Manage** and **Integration** (an in-app developer guide).
2. Select **Add endpoint**, enter a public `https://` URL, choose the events and select **Add endpoint**. Localhost and private addresses are refused.
3. Copy the **Signing secret** when it is shown; it is shown once.
4. Select **Send test** to confirm your endpoint answers. Use **Enable**, **Disable**, **Rotate secret** and **Delete** as needed.

A workspace can hold up to 25 endpoints. Each attempt has a 5 second response timeout, and delivery is at least once, so a delivery can arrive more than once. Verify the `X-Noxtica-Signature` header on every delivery. The envelope, events and retry rules are in [Webhooks](https://noxtica.com/docs/api/webhooks/). Identity events are in [Identity verification events and webhooks](https://noxtica.com/docs/identity-verification-webhooks/).

### 4. Create MCP, Score and ingestion credentials

- **MCP Tokens** and **Coding Agent Keys**: see [AI assistant, MCP tokens and coding-agent keys](https://noxtica.com/docs/backoffice/ai-assistant-and-mcp/).
- **Score API Keys**: create a key for server-side score calls. Store it on your server, never in browser or app code. Calls made with any key count toward the workspace. Revoke keys you no longer use.
- **Ingestion API Keys**: create a key for one project and environment, add it to your telemetry exporter, and revoke it when the service is retired.

Each of these pages has a **Manage** tab and an **Integration** tab with an in-app guide.

### 5. Send events to your SIEM

Open `Event Sinks`. A new sink is created disabled. Arm it, then send a real test request. The steps are in [Event sinks](https://noxtica.com/docs/backoffice/event-sinks/).

### 6. Set up alerts and reports

- `Alerts` has the tabs **Channels**, **Rules**, **History** and **Escalations**. Add a channel (email, Slack or webhook), create rules that decide when an alert fires, and review the delivery history. A workspace can hold up to 10 channels and 20 rules. Alert evaluation depends on the feature being enabled for your organisation.
- `Status Reports` sends periodic emails about traffic, detection activity, usage and quota. Reports are on by default. Choose the frequency, the time zone and an extra contact, and preview the next report.

### 7. Serve the collector from your hostname (Relay Hostnames)

Choose the domain and a hostname on your own domain, add the DNS record the page shows (a CNAME and, for verification, a TXT record), then wait until it verifies. When it does, the collector loads from your hostname. Creating, verifying and revoking need MFA. A domain's **Relay** tab shows the same status read-only. See [Content Security Policy, hosts and first-party relay](https://noxtica.com/docs/sdk/csp-and-relay/).

### 8. Register mobile apps (Attestation Apps)

Add the app identifier for each Android and iOS app. Noxtica then accepts attestation results from that app. Remove an app to stop trusting its results. Registering needs MFA. See [Device and app attestation](https://noxtica.com/docs/security/attestation/).

### 9. Connect other services (Connectors)

Pick the service (log provider, issue tracker, help desk or data warehouse), enter its credentials, and save. Credentials are stored encrypted and never shown again. Remove or update a connection at any time.

## Verify it works

- A new credential appears in its page's list with a created time, and **Last Used** updates after its first call.
- A test webhook shows a success message with the response status and time.
- On Script & Consent, **Check it works** confirms the script reaches Noxtica.
- On Relay Hostnames, the status badge changes to `active` once DNS verifies.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| The page is missing from the sidebar | The role is below Admin | Ask a workspace Admin |
| A create or revoke action prompts for a code | Sensitive change needs a fresh MFA check | Enter the authenticator code |
| Lost a secret | Secrets are shown once | Rotate or recreate the credential |
| Webhook URL is refused | It is not public `https`, or points to localhost or a private address | Use a public `https` URL |
| A key returns 403 from the API | The scope does not cover the call | Create a key with the needed scope; see [Authentication](https://noxtica.com/docs/api/authentication/) |
| Score API Keys page is empty or its API returns 404 | Self-serve score keys are not enabled for your organisation | Ask your account team |
| Relay hostname stays unverified | The DNS record is missing or wrong | Check the CNAME and TXT values shown on the page |

## Related

- [Backoffice guide: navigation, roles and shortcuts](https://noxtica.com/docs/backoffice/overview/): where each page sits in the sidebar.
- [Event sinks](https://noxtica.com/docs/backoffice/event-sinks/): SIEM export.
- [AI assistant, MCP tokens and coding-agent keys](https://noxtica.com/docs/backoffice/ai-assistant-and-mcp/): MCP and coding-agent credentials.
- [Server API](https://noxtica.com/docs/api/): endpoints, scopes and errors.
- [Roles and permissions](https://noxtica.com/docs/security/roles-and-permissions/): who can manage credentials.

---

Source: https://noxtica.com/docs/backoffice/workspace-settings/
Markdown: https://noxtica.com/docs/backoffice/workspace-settings/index.md
Last updated: 2026-10-27

# Workspace gates, feature flags, data operations and mobile operations

The **Administration** group of the sidebar holds the workspace controls that are not about detection: optional product behaviours, visitor experiments, deleting browser data and mobile posture. This page also covers your own **Settings** page and the notifications panel. A workspace Admin uses most of these pages; Analysts can read Feature Flags.

## What it is

Availability: Availability depends on your plan, role and the modules enabled for your organisation.

| Page | Route | Minimum role | Purpose |
| --- | --- | --- | --- |
| Workspace Gates | `/administration/workspace-gates` | Admin | Turn optional product behaviours on or off for this workspace |
| Feature Flags | `/feature-flags` | Analyst to read, Admin to change | Per-domain visitor experiences, experiment splits, conditional-recording keys |
| Data Operations | `/data-operations` | Admin | Soft-delete end-user browser data, run retention, remove admin accounts |
| Mobile Operations | `/mobile-operations` | Admin | Read mobile posture; arm or disarm the workspace's mobile kill-switch key |
| Settings | `/settings` | Any signed-in role | Your own sign-in security, appearance, notifications and privacy choices |

Sign-in, SSO and MFA enforcement are on **Sign-in & Access**, covered in [Sign-in, SSO, SCIM, MFA and IP allowlist](https://noxtica.com/docs/security/sign-in-and-access/). Users and roles are in [Roles and permissions](https://noxtica.com/docs/security/roles-and-permissions/). The audit log and exports are in [Audit log and data export](https://noxtica.com/docs/security/audit-log-and-exports/).

## Prerequisites

- The role in the table. See [Backoffice guide](https://noxtica.com/docs/backoffice/overview/).
- An authenticator app. Gates, flags, data operations and the mobile key each ask for a fresh MFA check.
- For Feature Flags: at least one registered domain. See [Domains, site keys and the install card](https://noxtica.com/docs/backoffice/domains/).
- For Data Operations: a clear reason for each deletion and the identifiers to match (device IDs, user ID, domain or dates).

## Steps

### 1. Review Workspace Gates

Open `Administration → Workspace Gates`. The page lists the gates your workspace can govern. These are product preferences, not legal assertions; assertions live in the [Legal basis register](https://noxtica.com/docs/compliance/legal-basis/).

For each gate you see its state (**On** or **Off**), whether this workspace overrides the platform default, and a note headed **What this switch does not stop**. Read that note: some gates change the Backoffice side of a feature while collection stays on the platform side.

- **Turn on**: some gates need an acknowledgement, and some also need you to type the gate key. Backoffice re-checks both on the server.
- **Turn off** and **Use platform default**: one click, no extra confirmation. Both still need a fresh MFA check and are audited.
- Every change is recorded in the audit log.

If no gate is controllable, the page says so.

### 2. Create a Feature Flag

Open `Administration → Feature Flags`. A flag controls a visitor experience on one domain, splits traffic for an experiment, or provides a key for conditional session recording.

1. Pick a domain, then select **New flag**.
2. **Flag key**: lowercase letters, numbers, dots, underscores or dashes. The key cannot change later.
3. **Description**: up to 500 characters.
4. **Rollout percentage**: the share of identified visitors admitted, from 0 to 100 with up to four decimals. Anonymous visitors always receive the default variant.
5. **Experiment variants** (optional): up to eight, each with a key and an allocation. Allocations must total 100 percent. Leave variants empty for a **Boolean flag**.
6. **Default variant**: what anonymous visitors and out-of-rollout visitors receive.
7. **Enabled**: allows assignment only when platform delivery is armed. Select **Create flag**.

On a flag's page you see **State**, **Identified rollout**, **30-day exposures** and **Reaching anyone**, the configured and observed split, and **Pinned subjects**. To pin a subject to a variant, enter the same email or user ID your integration sends; only a one-way hash is stored. Use the exact flag key in a conditional-recording trigger.

If the page says "Flag delivery is not armed", definitions are saved but visitors receive no assignments until Noxtica arms delivery for your workspace. Creating and changing flags needs the Admin role and an MFA check. Deleting a flag removes its variants and pins.

### 3. Run a Data Operation

Open `Administration → Data Operations`. Tabs: **End-User Data**, **Retention**, **Admin Accounts**, **History**. Every operation follows three steps: **Preview**, **Review impact**, **Confirm**.

- **End-User Data** soft-deletes browser intelligence data for chosen devices or users. Match by device IDs (one per line, up to 500), an external user ID, a domain or a date range. Add a reason, which goes to the audit log. Select **Preview Impact** and read the counts of fingerprints, events and visits.
- **Retention** triggers a manual retention cleanup of data older than your configured retention period. The page notes that an automatic retention run also happens daily at 03:00 UTC.
- **Admin Accounts** soft-deletes an operator, who can then no longer sign in. A reason is required.
- Type `DELETE` in capitals to unlock **Confirm Soft Delete**. Data is hidden from views and exports, and a platform superadmin can hard-delete it later. The **History** tab lists every run with its type, status and counts. A run that reaches the per-run row cap is marked **Partial**; run it again with tighter filters.

Data Operations applies to browser intelligence data. It does not apply to identity verification details or evidence. Noxtica does not remove those on a schedule; a tenant administrator removes them in `Backoffice → Identity Verification → KYC Verifications` (**Delete verification** and **Delete selected**) or through `KYC Erasure`. See [Verification data: storage, access and deletion](https://noxtica.com/docs/identity-verification-data/).

### 4. Read Mobile Operations

Open `Administration → Mobile Operations`. It shows **Fleet posture** and **Tenant posture** for these capabilities: **Mobile kill switch**, **Secure app handoff**, **Transactional activation**, **Account deletion**, **Android minimum version** and **iOS minimum version**. The page is read-only except for one control.

The kill switch has two keys: a fleet key that Noxtica operators control and a tenant key you control. Mobile access is killed only when both are on. Under **Tenant kill-switch control**, enter a **Change reason** (1 to 500 characters), then select **Arm tenant kill-switch key** or **Disarm tenant kill-switch key**, and confirm with MFA. If your key is armed, the page cannot observe the fleet key, so the effective posture shows as unknown rather than killed. Registered mobile apps and attestation results are covered in [Device and app attestation](https://noxtica.com/docs/security/attestation/).

### 5. Set your own account preferences

Open `Settings` (shortcut `G` then `S`). The page follows your account, not the workspace.

- **Security**: turn on two-step sign-in with an authenticator app, manage backup codes and review where you are signed in.
- **Appearance**: theme (Dark, Light, High contrast), density (Compact, Comfortable, Spacious) and interface font (Sans, Mono, Humanist, Mixed).
- **Notifications**: **Critical device email** (email when a device exceeds the configured risk threshold), **Weekly digest** (summary every Monday at 09:00 workspace time) and **In-app alerts**.
- **Privacy & cookies**: Noxtica's own security script always runs on the console to protect sign-in. Analytics, session replay and device recognition for your own console use are your choice and are off until you allow them.

The bell in the top bar opens **Notifications**: recent audit activity and destructive actions. Workspace-level alerts and reports are on [Integrations and API pages](https://noxtica.com/docs/backoffice/integrations/).

## Verify it works

- A changed gate shows its new state and "Turned on for this workspace." or "Turned off for this workspace.", and an audit entry appears.
- A new flag appears in the list with its **State**; after delivery is armed and traffic arrives, **30-day exposures** grow.
- After a data operation, **History** shows the run as **Completed**.
- After arming or disarming the tenant kill-switch key, the page shows its confirmation message and the tenant key state changes.
- Your notification choices stay after you reload **Settings**.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| No gates are listed | No gate is currently controllable per workspace | None; check back after a product update |
| A gate will not turn on | It needs an acknowledgement or the typed key | Complete the dialog |
| Flag assignments never reach visitors | Platform delivery is not armed, the flag is disabled, or rollout is 0 | Check the notices on the page; ask your account team |
| "Variant allocations must total 100%" | Allocations do not add up | Adjust them to total 100 |
| Preview Impact is disabled | No filter is set | Add device IDs, a user ID, a domain or dates |
| Too many device IDs | More than 500 IDs in one run | Split the run |
| Confirm button stays locked | `DELETE` was not typed exactly in capitals | Retype it |
| A run is marked Partial | It reached the per-run row cap | Run again with tighter filters |
| The kill-switch buttons are greyed out | No change reason entered | Enter a reason of 1 to 500 characters |
| Mobile page asks you to switch tenant scope | A platform operator has no workspace selected | Select a workspace |

## Related

- [Backoffice guide: navigation, roles and shortcuts](https://noxtica.com/docs/backoffice/overview/): where these pages sit.
- [Audit log and data export](https://noxtica.com/docs/security/audit-log-and-exports/): every change here is audited.
- [Data retention, raw IP storage and data locations](https://noxtica.com/docs/compliance/retention-and-locations/): retention settings.
- [Data subject scope, erasure requests and account deletion](https://noxtica.com/docs/compliance/requests-and-deletion/): erasure workflows.
- [Verification data: storage, access and deletion](https://noxtica.com/docs/identity-verification-data/): identity data lifecycle.
- [Sign-in, SSO, SCIM, MFA and IP allowlist](https://noxtica.com/docs/security/sign-in-and-access/): MFA and SSO.

---

Source: https://noxtica.com/docs/billing/plans-and-packages/
Markdown: https://noxtica.com/docs/billing/plans-and-packages/index.md
Last updated: 2026-10-27

# Plans, packages and add-ons

This page covers the Backoffice pages that show your plan, the packages and add-ons you can have, and how to ask for changes. It describes pages and behaviour. It states no prices, rates or quota values. For those, see the [pricing page](https://noxtica.com/pricing/) and your agreement.

## What it is

Availability: Availability depends on your plan, role and the modules enabled for your organisation.

Self-serve purchase of packages and add-ons is available when it is enabled for your organisation. Otherwise your account team provisions them. Backoffice tells you which case applies on the page itself.

| Term | What it means in Backoffice |
| --- | --- |
| Plan | Your base tier. It sets your monthly allowances and your domain limit. |
| Plan change request | A request to move to another plan. A platform administrator reviews it. |
| Add-on request | A request for extra events or extra collector requests on top of your plan. A platform administrator reviews it. |
| Package | A bundle that turns on the core modules of one or more product areas for a monthly fee. |
| Module add-on | A single optional module you can turn on or off for your workspace. |

Where the pages are, under Backoffice → Billing & Plan:

| Page | Route | Who can open it |
| --- | --- | --- |
| Plan | `/billing/plan` | Admin sees it in the menu. |
| Packages & Add-ons | `/billing/packages` | Admin role, or billing role when enabled for your organisation. |

Packages & Add-ons has four tabs: **Packages**, **Add-ons**, **Included usage** and **Billing status**. The Add-ons tab is shown only to roles that may manage it, which means the admin role.

Prices, if shown, are the values in force for your workspace. This page does not repeat them.

## Prerequisites

- The admin role to request a plan change, request an add-on, or turn a module add-on on or off. See [Roles and permissions](https://noxtica.com/docs/security/roles-and-permissions/).
- The admin role or the billing role to subscribe to or cancel a package. The billing role is available when enabled for your organisation.
- MFA enrolled on your account. Subscribing, cancelling and module toggles ask for a step-up check from the last 6 hours. Plan and add-on requests do not.
- Wallet funds to subscribe to a priced package. Subscribing charges your wallet. See [Wallet, invoices and reports](https://noxtica.com/docs/billing/wallet-invoices-reports/).
- Self-serve purchase enabled for your organisation, if you want to subscribe yourself. Otherwise ask your account team.

## Steps

### 1. Review your current plan

Go to Backoffice → Billing & Plan → **Plan**. The **Plan & Quotas** card shows your plan name, the monthly event limit and the maximum domains.

The **Request plan change** card below it shows **Your current plan** with its allowances: events, API requests, ingestion requests, Score API calls, AI credits, domains and data retention. It also shows the monthly price and where that price comes from: **Plan price**, **Your negotiated price** or **Custom plan default**.

### 2. Request a plan change or extra capacity

On the same page, choose a tab.

**Change plan**

1. Choose **Select new plan**. Each option is marked as an upgrade or a downgrade.
2. Read **What changes**. It compares your current plan with the new plan, allowance by allowance.
3. Add an optional **Reason**.
4. Click **Submit request**.

**Add-ons**

1. Choose a resource: **Additional API requests** (collector requests) or **Additional events**.
2. Choose a quantity. Backoffice shows an estimated monthly price.
3. Enter a **Reason**. It is required on this tab.
4. Click **Request add-on**.

After you submit, a **Pending** badge shows and the page reads **Your plan change request is awaiting review**, or the same for an add-on request. You can have one pending request for each type. You cannot withdraw a request from Backoffice. Contact your account team to cancel it before review.

What happens next:

- A platform administrator reviews the request. Nothing changes until it is approved.
- Plan pricing and billing are confirmed by your account team after approval.
- No card is charged in the product for a plan or add-on request. Approved add-ons recur monthly until cancelled.
- Add-ons stack on top of your plan and are used after your plan allowance runs out.
- A plan change does not retroactively shrink the limit of a month that has already started.

### 3. Compare packages

Go to Backoffice → Billing & Plan → **Packages & Add-ons**. The **Packages** tab shows one card for each package:

- The package name and description.
- A badge: **Current plan**, **Cancelling** or **Not subscribed**.
- The monthly price, **Free**, **Coming soon** or **Price unavailable**.
- **Covers:** the product areas the package turns on.
- **Next charge:** the date of the next charge, for an active package.

A note under the cards reads **Subscribing charges your wallet balance** and links to **Top up your wallet**.

### 4. Read why an item is unavailable

When you cannot subscribe or turn something on, the card or row shows a badge and a plain reason before you click. The control is disabled and points at that reason.

| Badge | Reason shown | What you can do |
| --- | --- | --- |
| **Requires <plan> plan** | The item needs a higher plan. | Click **request a plan change**. Backoffice shows your workspace ID so you can quote it. |
| **Core module needed** | Turn on the core module of this product first. | Turn on the core module, or subscribe to a package that includes it. |
| **Embargoed** | A sale embargo applies. For attestation the text is **Embargoed until hardware verification is proven.** | Contact Noxtica support and name the item. Quote your workspace ID. |
| **Pending legal review** | The item waits for legal sign-off, for example behavioral data or the EU AI Act active tier. | Contact Noxtica support and name the item. |
| **Not available yet** | The item is on hold or still being built. | Contact Noxtica support and name the item. |
| **No price set yet** | A package has no price while self-serve billing is on. | Contact Noxtica support and name the package. |

Backoffice has no waitlist. For a held item, contact support and quote the workspace ID. Use the copy button next to it.

### 5. Subscribe to a package

1. On the **Packages** tab, click **Subscribe** on a card. The button reads **Activate** when the package is free or when self-serve billing is not enabled.
2. Complete the step-up prompt.
3. Read the result: **Subscribed.**

Subscribing charges your wallet. If the balance is too low you see **Your wallet balance is too low** with a **Top up your wallet** button. Nothing is charged and nothing changes.

### 6. Cancel a package

On an active package card, click **Cancel package** and complete the step-up prompt. The card changes to **Cancelling** and shows **Package cancelled.** A cancelled package cannot be subscribed again from Backoffice. Ask your account team if you need it back. Cancelling does not delete your data or your audit history.

### 7. Turn module add-ons on or off

Open the **Add-ons** tab. It lists the module add-ons published for your workspace. Each row shows **Subscribed** or **Not subscribed**, its monthly fee or **No monthly fee**, and whether it turns on for your whole workspace or per domain.

1. Switch the toggle for the module.
2. Complete the step-up prompt.
3. Read **Add-on subscribed.** or **Add-on unsubscribed.**

Items that cannot be turned on are listed under **Not available yet**, each with its reason and the next step, as in step 4. If module add-ons are not enabled for your organisation, Backoffice shows a banner and the controls are read-only. Subscribing records the add-on and its monthly fee. The charge is not taken at the click.

The **Included usage** tab and the **Billing status** tab are covered in [Usage, quotas and metering](https://noxtica.com/docs/billing/usage-and-quotas/) and [Billing status, grace period and reminders](https://noxtica.com/docs/billing/status-grace-reminders/).

## Verify it works

- A submitted request shows **Pending** and the submission date on the Plan page.
- The request appears in the audit log as Plan Requested or Extra Quota Requested. See [Audit log and data export](https://noxtica.com/docs/security/audit-log-and-exports/).
- A subscribed package card shows **Current plan** and a **Next charge** date. Your wallet activity shows the package charge.
- A module row shows **Subscribed**.
- A cancelled package shows **Cancelling**.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| The Plan page is missing from the menu | Your role is below admin. | Ask an admin. |
| **A pending plan change request already exists. Please wait for it to be reviewed.** | One request of that type is already pending. | Wait for the review, or contact your account team to cancel it. |
| **A pending extra-quota request already exists. Please wait for it to be reviewed.** | One add-on request is already pending. | Same as above. |
| **You are already on this plan** | The chosen plan is your current plan. | Choose another plan. |
| The Subscribe button is disabled with a badge | A reason applies, for example plan tier or a hold. | Read the reason and follow the action in step 4. |
| **Your wallet balance is too low** | The wallet cannot cover the package fee. | Click **Top up your wallet**, then subscribe again. |
| **No packages available** | No package is published for your workspace. | Ask your account team. |
| **No package can be subscribed to yet** | Every package is on hold or has no price. | Contact Noxtica support and quote your workspace ID. A platform administrator can assign a package or extend a grace period. |
| **This change could not be applied** | The change was refused and nothing was changed. | Retry. Contact support with the time of the attempt if it repeats. |
| A cancelled package cannot be subscribed again | Packages in Cancelling or off state cannot be activated again. | Ask your account team. |
| The Add-ons tab is missing | Your role is below admin. | Ask an admin. |
| A banner says module add-ons are disabled | Module add-ons are not enabled for your organisation. | Ask your account team. |
| **Package billing is not enforced for this workspace yet** | Self-serve billing is not enabled for your workspace. | Nothing is charged and no page is paused. Ask your account team to provision the package. |
| **Verification cancelled** | You closed the step-up prompt. | Repeat the action and verify. |

## Related

- [Usage, quotas and metering](https://noxtica.com/docs/billing/usage-and-quotas/): meters, quota rules and the Included usage tab.
- [Wallet, invoices and reports](https://noxtica.com/docs/billing/wallet-invoices-reports/): add funds, invoices and reports.
- [Billing status, grace period and reminders](https://noxtica.com/docs/billing/status-grace-reminders/): the Billing status tab and the grace window.
- [Roles and permissions](https://noxtica.com/docs/security/roles-and-permissions/): who can see and change billing pages.
- [Pricing](https://noxtica.com/pricing/): plan and rate information. [Pricing reference](https://noxtica.com/docs/pricing/) has the definitions behind it.

---

Source: https://noxtica.com/docs/billing/usage-and-quotas/
Markdown: https://noxtica.com/docs/billing/usage-and-quotas/index.md
Last updated: 2026-10-27

# Usage, quotas and metering

Usage & Quotas shows what your workspace has used this month against what your plan includes. This page explains the tabs, how each meter counts, and what happens when you reach a limit. It states no quota values and no prices. Backoffice shows the values in force for your workspace. See [pricing](https://noxtica.com/pricing/) and your agreement for commercial terms.

## What it is

Availability: Availability depends on your plan, role and the modules enabled for your organisation.

Usage & Quotas is under Backoffice → Billing & Plan → **Usage & Quotas** (`/usage`). Viewers, analysts, admins and billing users can open it. Some sections need more than view access.

| Tab | Content | Needs |
| --- | --- | --- |
| **Overview** | Usage against quota for events, collector requests, ingestion requests, Score API calls, AI credits, MCP queries and domains. Burn-down chart. Usage by domain. Plan limits. | View access |
| **Meters & quotas** | One row for each meter, with usage, quota, projection and status. Usage by store. Usage by functionality and endpoint. | The capability to view billing: admin or billing role |
| **AI & agents** | AI Assistant usage. Agent and MCP usage. LLM sourcing usage. | View access. Agent and MCP usage needs the admin role. LLM sourcing usage needs the admin role. |
| **KYC & identity** | Verifications this period and an estimated spend. | The capability to view KYC usage: any role |
| **PAYG & wallet** | Module add-ons, pay-as-you-go accrual and wallet balances. | View access |
| **History** | Recent wallet activity and pay-as-you-go close-outs. | View access |

Old links still work. `/billing/usage` opens the **Meters & quotas** tab and `/ai-usage` opens **AI & agents**.

### Quota rules in plain words

All counters run on the UTC calendar month. They reset at the start of each month.

| Meter | What counts | At the limit |
| --- | --- | --- |
| Collector requests | Each token issuance request to the collector. | When quota enforcement is enabled for your organisation, a further token request is refused with `429`, code `COLLECTOR_REQUESTS_QUOTA_EXCEEDED`, and a `Retry-After` header with the seconds until next month. Without enforcement the counter fills and nothing is refused. |
| Events | Each event submission. | The same enforcement setting applies. |
| Ingestion requests | Each authenticated request served by the ingestion service in native mode. Proxied and unauthenticated requests are excluded. The quota is 10 times your collector request quota. | Counted and shown. Never blocked. |
| Score API calls | Each authenticated, valid `POST /v1/score` call. | Calls above the included amount are billed as metered usage and are never rejected. |
| AI credits | AI Assistant use. The plan gives a monthly allotment. Purchased extra credits stay until used. | Backoffice shows Remaining. |
| MCP queries | MCP tool use against a monthly cap for the token scope tier. | Backoffice labels it **Enforced — counts toward your monthly cap** or **Shadow only — not yet enforced**. |
| Domains | Active domains against the plan maximum. | Creating another domain is refused with **Maximum domains limit reached for this tenant**. |

Two further points:

- A meter with no enforced quota shows **Count only — no enforced quota**.
- Each plan includes a share of the listed monthly allowances for module meters, rounded down to a whole unit. Whether an overage price applies depends on your plan. Where a plan sells no overage the table shows **Hard cap**.

Some figures are estimates. The page labels them. **Billable units** and pay-as-you-go accrual are estimated and display-only. What you are charged appears on your [invoices](https://noxtica.com/docs/billing/wallet-invoices-reports/).

## Prerequisites

- A Backoffice user with at least view access for the Overview. The admin role or the billing role for **Meters & quotas**.
- A workspace with traffic. A new workspace shows **No usage recorded yet**.
- For KYC usage: the identity verification module activated for your workspace. Otherwise the tab says **Not activated**.
- For quota alerts: the admin role, and alert delivery set up. See [Uptime checks, alerts, status reports and the status page](https://noxtica.com/docs/observability/uptime-alerts-status/).

## Steps

### 1. Open Usage & Quotas

Go to Backoffice → Billing & Plan → **Usage & Quotas**. The subtitle shows the period. The tab you open is kept in the `?tab=` part of the address, so you can bookmark it.

### 2. Read the Overview

Each quota card shows the used amount, the limit and **N% used**. The footer reads:

- **Healthy** below 75 percent.
- **Approaching limit** from 75 percent.
- **Over 90% — upgrade recommended** from 90 percent.

The **Quota burn-down** chart draws cumulative usage and a straight-line projection to month end. It says **Within quota**, **Projected to exhaust on ~<date>** or **Quota exhausted on <date>**. A plan without a monthly event quota shows no limit line.

**Usage by domain** lists Domain, Status, Submissions and Visits for the period. **Plan limits** lists the static limits of your plan.

Backoffice labels figures by what they are:

- **Usage vs quota**: the metered counters your plan is measured against.
- **Analytics & trend**: raw event volume. These are trend metrics, not billing counters, and can exceed the quota count.
- **Observed (not billed)**: read-only meters shown for visibility.
- **Billable units (post free-tier)**: an estimate, display only.

### 3. Read the meters

Open **Meters & quotas**. Use **Filter by group** for All groups, Plan-included, Pay-as-you-go or Observability. Each row shows:

| Column | Meaning |
| --- | --- |
| Meter | The feature axis, with a link to its page. |
| Used / quota | Usage and the ceiling, with a percent bar. |
| Projected month-end | A straight-line projection. Monthly meters only. |
| Last 14 days | A trend line for meters with daily data. |
| Rate | The pay-as-you-go rate code and unit price, when the meter is billed. |
| Status | **Within quota**, **Over quota**, **Tier-included** or **No ceiling**. |

Below the table:

- **Usage by store** lists rows and estimated size this calendar month for each data class: Event data, Event payloads, Metrics, Warehouse analytics and KYC evidence, by storage location.
- **Usage by functionality and endpoint** shows what the Collect and Ingest endpoints served in a UTC month, per meter, against the included quantity, with % used and any overage. Choose the period with the selector.
- For KYC usage the section can show a **Shadow invoice — not billed**: what the period would cost under the rate card. The page states the rate card version and status. When a rate card is a proposal, the figures are informational and nothing is enforced or billed against them.

### 4. Compare plans

Open Backoffice → Billing & Plan → Packages & Add-ons → **Included usage**. The table has one row for each meter and one column for each plan. A cell shows the monthly included quantity and the overage price per unit, or **Hard cap**. Your plan column is marked **Your plan**. A badge says whether the rate card is active or **Proposed — not billed**.

### 5. Read KYC usage

Open **KYC & identity**. It shows **Verifications this period** and **Estimated KYC spend (this period)**. The spend is a display-only estimate. Use the pricing page for the rate card.

### 6. Check pay-as-you-go and wallet

Open **PAYG & wallet** for module add-on state, estimated pay-as-you-go accrual and wallet balances. Open **History** for the latest wallet entries and pay-as-you-go close-outs. Full wallet detail is under Billing & Plan → Wallet.

### 7. Set a quota alert

Go to Backoffice → Integrations & API → **Alerts** → rules.

1. Add a rule from the **Quota usage** template. It alerts when this workspace's monthly quota usage reaches the threshold percentage.
2. Set the threshold between 50 and 100 percent. The default is 90. The rule evaluates over one day.
3. Choose one or more alert channels and save. The save needs a step-up check.

Rules can be written even when the evaluator is paused for your organisation. Backoffice shows a banner when it is. Status-report e-mails also summarise usage and quota. See [Wallet, invoices and reports](https://noxtica.com/docs/billing/wallet-invoices-reports/).

## Verify it works

- The Overview shows a period in the subtitle and your quota cards with percentages.
- The burn-down chart shows a cumulative line that grows through the month.
- **Meters & quotas** lists meters with a **Status** for each.
- A quota alert rule shows in the Alerts list with its condition and state.
- After the month changes, the counters start again from zero.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| **Failed to load usage data** | The overview read failed. | Click **Retry**. Other tabs load their own data. |
| **This report is temporarily unavailable.** | A section read failed. | Click **Retry**. |
| **Unavailable** on a card | That metric could not be read. | Retry later. |
| **No usage recorded yet** | No billable events in the current period. | Send traffic, or check the domain install. |
| Analytics events are higher than the Events quota count | Analytics volume includes rejected and removed events. It is a trend metric. | Use **Usage vs quota** for the billing counter. |
| **This plan has no monthly event quota, so no limit line is shown.** | Your plan has no event quota. | None needed. |
| No ingestion quota line | No collector request quota is set, and the ingestion quota is 10 times it. | None needed. |
| **No quota** or **No allowance** on a meter | The plan has no rate-card row for that meter. | Ask your account team. |
| Meters & quotas tab is missing | Your role has no view-billing capability. | Ask an admin or use the billing role. |
| Token requests return `429` with `COLLECTOR_REQUESTS_QUOTA_EXCEEDED` | Quota enforcement is enabled and the collector request quota is used up. | Wait for the next UTC month or request more capacity. See [Plans, packages and add-ons](https://noxtica.com/docs/billing/plans-and-packages/). |
| **Maximum domains limit reached for this tenant** | You reached the plan domain limit. | Remove a domain, or request a plan change. |
| **Not activated** on KYC & identity | The identity verification module is not activated. | Ask your account team. |
| **Per-store usage appears here once the daily store-usage rollup has run** | The daily rollup has not run for this workspace. | Check again later. |
| A rate card badge says **Proposed — not billed** | The rate card is not active. The figures are informational. | Use invoices for amounts charged. |

## Related

- [Plans, packages and add-ons](https://noxtica.com/docs/billing/plans-and-packages/): request more capacity.
- [Wallet, invoices and reports](https://noxtica.com/docs/billing/wallet-invoices-reports/): wallet, invoices and status reports.
- [Billing status, grace period and reminders](https://noxtica.com/docs/billing/status-grace-reminders/): banners and reminders.
- [Uptime checks, alerts, status reports and the status page](https://noxtica.com/docs/observability/uptime-alerts-status/): alert channels and rules.
- [Pricing reference](https://noxtica.com/docs/pricing/): the definitions of collector request, event, ingestion request and Score API call.

---

Source: https://noxtica.com/docs/billing/wallet-invoices-reports/
Markdown: https://noxtica.com/docs/billing/wallet-invoices-reports/index.md
Last updated: 2026-10-27

# Wallet, invoices and reports

The wallet is your prepaid balance. Package fees and other charges draw on it. Invoices are the monthly statements. Reports are the periodic usage and status e-mails. This page covers the Backoffice pages for all three. It states no amounts. See [pricing](https://noxtica.com/pricing/) and your agreement for commercial terms.

## What it is

Availability: Availability depends on your plan, role and the modules enabled for your organisation.

| Page | Route | Who can open it |
| --- | --- | --- |
| Wallet | `/billing/wallet` | Admin role, or billing role when enabled for your organisation |
| Invoices | `/billing/invoices` | Same |
| Monthly Reports | `/billing/reports` | Same |
| Status Reports | `/integrations/status-reports` | Admin role |

All are under Backoffice → Billing & Plan, except Status Reports, which is under Integrations & API. Adding funds needs the capability to manage billing and a step-up MFA check from the last 6 hours. Reading needs only the capability to view billing.

When the wallet is not enabled for your workspace, the Wallet page says **Wallet not enabled**. Your account team can turn it on.

Self-serve credit packs for AI Assistant credits are available when self-serve purchase is enabled for your organisation. Otherwise your account team provisions them.

## Prerequisites

- The admin role or the billing role. See [Roles and permissions](https://noxtica.com/docs/security/roles-and-permissions/).
- MFA enrolled on your account.
- The wallet enabled for your workspace, and a payment set up for it. If it is not, Backoffice says **This workspace isn't set up for payments yet. Contact your administrator to enable billing.**
- For the low-balance warning e-mail: the warning sweep enabled for your organisation. The preference is saved either way.

## Steps

### 1. Read your balances

Go to Backoffice → Billing & Plan → **Wallet**. Each currency has a card with:

| Field | Meaning |
| --- | --- |
| Balance | What the wallet holds. |
| Available | The balance minus holds. It turns red when negative. |
| Negative-balance allowance | How far below zero charges may go. A platform administrator sets it. |
| Platform floor | The lowest balance the platform allows for that currency. |

A **Low balance** badge shows when the balance is under your warning threshold. A new wallet shows **No balances yet** until a credit lands.

### 2. Add funds

In the **Add funds** card:

1. Choose a **Currency**. The rail follows the currency. A card currency opens a secure checkout page. A crypto currency gives you a deposit address. The baseline set is USD, USDT and USDC. EUR, GBP, TRY and EUROC appear when multi-currency is enabled for your organisation.
2. For crypto, choose a **Network**: default, TRC20 or ERC20.
3. Enter the **Amount**.
4. Click **Add funds** and complete the step-up prompt.

For a card, Backoffice redirects you to the hosted checkout. For crypto, the address, the amount and an expiry countdown appear inline. Send the deposit before it expires. If it expires, start a new top-up.

Funds are credited after the payment is confirmed. They are not credited when you return from checkout, and a crypto deposit is credited after on-chain confirmation. A top-up still waiting to settle shows under **Pending top-ups** as Card or Crypto, with its start date. Your balance updates after confirmation.

### 3. Set a low-balance warning

In the **Low-balance warning** card, enter an **Amount** and click **Save**. Leave it blank to use the default, which is a percentage of your last invoice with a minimum. The card shows **Currently warns below <value>**. The card applies to the USD wallet. It is shown only to roles that manage billing. Saving needs no step-up check.

You get one e-mail when the balance crosses below the threshold. You do not get another while it stays below. Recovery sends no e-mail. See [Billing status, grace period and reminders](https://noxtica.com/docs/billing/status-grace-reminders/).

### 4. Check AI credits

The **AI credits** card shows **Monthly allotment**, **Used this period**, **Extra credits** and **Remaining**. A custom plan can read **Unlimited (custom plan)**. The monthly allotment resets each month in UTC. Purchased extra credits stay until used and are consumed after the monthly allotment.

When self-serve purchase is enabled for your organisation, **Buy AI credits** lists the available packs. One credit is 1,000 assistant tokens.

1. Click **Buy credit pack** on a pack and complete the step-up prompt.
2. Pay on the hosted checkout page.
3. Credits appear after payment is confirmed, on your next visit.

The buy button needs the admin role. If purchase is not enabled you see **Buying AI credits isn't available yet for this environment.** Ask your account team.

### 5. Read and export the ledger

**Recent activity** lists every wallet entry. Filter by currency, entry type (Top-up, Charge, Refund, Conversion, Adjustment), direction (Credit, Debit) and a From and To date. Choose 25, 50 or 100 rows to a page. The default is 50. Columns include date, type, direction, amount, currency, provider, payment reference and memo. Click **Download CSV** to export the filtered view.

### 6. Open an invoice

Go to Backoffice → Billing & Plan → **Invoices**. The list shows Period, Status, Total, Issued and Due. Click **Open**.

| Status | Meaning |
| --- | --- |
| Draft | Not yet issued. |
| Issued | Issued and open. |
| Paid | Settled. |
| Unpaid | Not settled. It counts toward the **Unpaid invoices** banner and reminder e-mails. |
| Void | Cancelled. |

An invoice for a month is created after the month ends. It combines plan, package, module, pay-as-you-go, AI-credit and speech lines in one statement. AI-credit and speech lines show consumption and carry no amount. Click **Download** on the detail page. It opens a print-ready page in a new tab. Use your browser's print function to save a PDF.

Only a platform administrator, with a second administrator approving, can void or reissue an invoice.

Wallet settlement of an invoice depends on your organisation. When it is enabled, a successful debit marks the invoice **Paid** and a failure for insufficient funds marks it **Unpaid**.

### 7. Review reports

Go to Backoffice → Billing & Plan → **Monthly Reports**. The page lists past reports, up to the 50 most recent. Each row shows Period, Cadence (Monthly, Weekly or Daily), Sent, and Status:

| Status | Meaning |
| --- | --- |
| Sent | At least one recipient was sent the report. |
| Suppressed | No recipient was sent it and at least one was suppressed. |
| Failed | No recipient was sent it. |

Click **Open** to see the exact report that was sent. It is a stored copy, not a new calculation. **Snapshot unavailable** means no copy was stored for that send. A Daily Report panel lets a workspace admin opt in to a short AI-written summary that uses AI credits. It does not turn on e-mail delivery.

### 8. Choose who gets status reports

Go to Backoffice → Integrations & API → **Status Reports**.

1. Leave **Send periodic status reports to workspace admins** on, or switch it off. It is on by default. An opt-out always wins.
2. Optionally enter a **Nominated external contact**. It is an extra recipient outside your admin list.
3. Optionally enter a **Display timezone**, an IANA name such as `Europe/Paris`. It changes only how dates are shown. Blank means UTC.
4. Save and complete the step-up prompt.
5. Click **Preview** to render your next report with live data. Nothing is sent.

Recipients of reports and billing notices are every active workspace admin plus the nominated contact. The billing role is not a recipient by role. Nominate a finance address as the contact if finance staff need the e-mails.

A note reads **Report delivery is not active yet** while delivery is not enabled for your organisation. Your choice is recorded now.

## Verify it works

- After a card top-up is confirmed, the wallet **Balance** rises and the ledger shows a **Top-up** credit. The pending top-up leaves the **Pending top-ups** card.
- A saved threshold shows **Currently warns below <value>**.
- Invoices lists a row for each closed month with a status.
- **Open** on a report row shows the stored report.
- Status Reports shows **Enabled (default)** or **Turned off for this workspace**.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| **Wallet not enabled** | The wallet is not enabled for the workspace. | Ask your account team. |
| **The wallet isn't available yet for this workspace.** | The wallet or payment rail is not enabled. | Ask your account team. |
| **Top-up is temporarily unavailable. Please try again later.** | The checkout service is not available. | Retry later. |
| **This workspace isn't set up for payments yet.** | No payment account is linked to the workspace. | Contact your account team. |
| **You're starting top-ups too frequently.** | Rate limit. | Wait a moment and retry. |
| **That currency isn't available on this workspace yet.** | A multi-currency option is not enabled. | Choose a baseline currency. |
| A top-up is not credited | Payment is not confirmed yet. | Check **Pending top-ups**. For crypto, wait for on-chain confirmation. |
| This deposit address has expired | A crypto address has a time limit. | Start a new top-up. |
| The Low-balance warning card is missing | Your role does not manage billing. | Use an admin account. |
| **No invoices yet** | No month has been closed for the workspace. | Check after the initial month ends. |
| **No reports yet** or **Reports have not run yet** | No periodic report was composed yet. | Check after the next scheduled send. |
| **Snapshot unavailable** | No copy was stored for that send. | None. Older sends can lack a copy. |
| Nobody receives reports | Status reports are switched off, or delivery is not enabled. | Check the Status Reports page and ask your account team. |

## Related

- [Billing status, grace period and reminders](https://noxtica.com/docs/billing/status-grace-reminders/): banners, grace window and reminder schedule.
- [Plans, packages and add-ons](https://noxtica.com/docs/billing/plans-and-packages/): what charges your wallet.
- [Usage, quotas and metering](https://noxtica.com/docs/billing/usage-and-quotas/): usage against quota.
- [Roles and permissions](https://noxtica.com/docs/security/roles-and-permissions/): the billing role.
- [Terms of Service](https://noxtica.com/terms/): fees, billing and payment.

---

Source: https://noxtica.com/docs/billing/status-grace-reminders/
Markdown: https://noxtica.com/docs/billing/status-grace-reminders/index.md
Last updated: 2026-10-27

# Billing status, grace period and reminders

Backoffice tells you about billing problems in three ways: a banner at the top of every page, a grace-period notice when a package is required, and reminder e-mails. This page explains each one, what it does and does not affect, and what to do. It states no amounts. See [pricing](https://noxtica.com/pricing/) and your agreement for commercial terms.

## What it is

Availability: Availability depends on your plan, role and the modules enabled for your organisation.

| Signal | Where | Blocks anything? |
| --- | --- | --- |
| Billing status banner | Top of every Backoffice page | No |
| Package grace notice | Banner, and the **Billing status** tab of Packages & Add-ons | No, until the window ends |
| Package grace gate | Replaces most Backoffice pages after the window ends | Backoffice pages only |
| Reminder e-mails | Your admins' inboxes | No |

Billing signals reach roles that can view billing: the admin role and, when enabled for your organisation, the billing role. Other roles see no banner.

### Billing status banner

Backoffice shows at most one banner. It picks the most severe:

| Order | Banner | Button | Can you hide it? |
| --- | --- | --- | --- |
| 1 | **Wallet balance is negative** | **Add funds** | No |
| 2 | **Unpaid invoices** with the count | **View invoices** | No |
| 3 | **Wallet balance is running low** | **Top up** | Yes, for 1 day |

A banner only informs. It never blocks a page. The negative-balance and low-balance banners show only when the wallet is enabled for your workspace.

### Package grace window

When package billing is enforced for your workspace, the workspace needs one active package. A grace window gives you time to choose one. Package billing is enforced when self-serve purchase is enabled for your organisation. Otherwise the Billing status tab says **Package billing is not enforced for this workspace yet: nothing is charged and no page is paused.**

The window is a date. Workspaces created through the platform console start with a 30-day window. A platform administrator can extend it. Yours can differ, and the Billing status tab shows the date.

The notice changes as the date nears:

| Days left | Notice | Can you hide it? |
| --- | --- | --- |
| More than 14 | Information | Yes, for 7 days |
| 4 to 14 | Warning | Yes, for 1 day |
| 3 or fewer | Warning | No |
| Ended, no active package | Critical, and the gate applies | No |

A workspace with an active package is never gated. A Noxtica platform administrator is never gated. If no deadline is recorded for your workspace, the notice says **No grace deadline is set for this workspace.** and nothing pauses.

### What the gate pauses

When the window has ended and no package is active, Backoffice replaces the page you opened with **Choose a package to continue**, or **This workspace needs an active package** when you cannot choose one.

- It pauses Backoffice pages. The text says every console page except Billing & Plan and Settings.
- In the code, the pages that stay open are Packages & Add-ons (`/billing/packages`) and Settings (`/settings`). Other Billing & Plan pages such as Wallet and Invoices are paused too. Treat the page text as the intent and the list in this paragraph as what the console does.
- Data collection is not affected. The gate lives in the Backoffice console. Collection and the Server API do not read it, so tokens, events, scoring and your API keys keep working.
- Nothing is deleted.

### Reminder e-mails

Three reminders run in a daily scheduled job. Each one is enabled separately for your organisation, so you may receive some and not others.

| Reminder | Sent when | Repeats |
| --- | --- | --- |
| Low balance | The USD wallet balance moves from above (or unknown) to below your threshold | Not while it stays below. Recovery sends nothing. |
| Unpaid invoice | An invoice is unpaid 3, 7 and 14 days after its due date | One e-mail at each of the three stages for that invoice. A new invoice restarts the count. |
| Subscription payment | An active module subscription is not yet charged for the current month, on day 3, 7 and 14 of the UTC calendar month | One e-mail at each stage. The text says reminder 1, 2 or 3 of 3. |

A separate one-time e-mail is sent when an invoice is issued. No reminder cancels a subscription.

Reminders go to every active workspace admin and to the nominated report contact, in English, up to 26 recipients. Each e-mail links to your wallet or invoice. A recipient who is suppressed is skipped. Each reminder is written to the audit log with the user **System**.

## Prerequisites

- The admin role, or the billing role when enabled for your organisation. See [Roles and permissions](https://noxtica.com/docs/security/roles-and-permissions/).
- To clear a negative balance: MFA enrolled, so you can pass the step-up check when you add funds.
- To end a gate: wallet funds for a priced package, and the capability to manage billing. If no package can be chosen, you need a platform administrator.

## Steps

### 1. Clear a banner

- **Wallet balance is negative** or **running low**: click the button, go to Wallet and add funds. See [Wallet, invoices and reports](https://noxtica.com/docs/billing/wallet-invoices-reports/).
- **Unpaid invoices**: click **View invoices**, open each invoice with status Unpaid and add funds. A wallet charge for an open invoice depends on your organisation. If you are unsure, ask your account team.
- Hide a low-balance banner for a day with its hide button if you have already planned the top-up.

### 2. Read the grace state

Go to Backoffice → Billing & Plan → **Packages & Add-ons** → **Billing status**. The **Package access** card gives one of these statements:

- **A package is active, so console access is not restricted.**
- **The grace period ends on <date>** with the days left.
- **The grace period ended on <date>.** Pages are paused.
- **No grace deadline is set for this workspace.**
- **Package billing is not enforced for this workspace yet.**

**Active packages** lists each active package with its **Next charge** date.

### 3. Choose a package before the window ends

1. Open the **Packages** tab.
2. Click **Subscribe** on a package you can subscribe to. Complete the step-up prompt.
3. Check that **Billing status** now says a package is active.

Reasons a package may be unavailable are in [Plans, packages and add-ons](https://noxtica.com/docs/billing/plans-and-packages/).

### 4. When no package can be chosen

If every package is on hold or has no price, Backoffice says **No package can be subscribed to yet**. Only a platform administrator can extend your grace period or assign a package. Contact them and quote your workspace ID. Copy it with the button next to it on the page. A platform administrator extends or sets the window with a recorded reason and cannot set it more than 366 days ahead. You cannot do this yourself.

### 5. Keep reminders reaching the right people

Nominate a finance address on Backoffice → Integrations & API → **Status Reports**. Billing reminders use the same recipient list as status reports.

## Verify it works

- After you add funds and the payment is confirmed, the negative or low-balance banner disappears on your next page load.
- After you subscribe, the Billing status tab says a package is active and the grace banner no longer shows.
- The audit log shows the reminder rows, for example `money.low_balance_warned`, with the user **System**. See [Audit log and data export](https://noxtica.com/docs/security/audit-log-and-exports/).

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| No billing banner at all | Your role cannot view billing, or the wallet is not enabled and no invoice is unpaid. | Use an admin account. |
| The banner stays after you added funds | The payment is not confirmed yet. | Check **Pending top-ups** on the Wallet page. Reload after it settles. |
| **Choose a package to continue** covers a page | The grace window ended with no active package. | Subscribe to a package. Packages & Add-ons and Settings stay open. |
| **This workspace needs an active package** | You cannot subscribe, or no package can be subscribed to. | Ask a workspace admin or billing admin. If none can, contact a platform administrator with your workspace ID. |
| **Your wallet balance is too low** | The package fee is more than the balance. | Top up your wallet, then subscribe again. |
| Wallet or Invoices pages are paused by the gate | The gate pauses Billing & Plan pages other than Packages & Add-ons. | Subscribe from Packages & Add-ons. If funds are needed first, contact a platform administrator. |
| Collection still works while Backoffice is paused | By design. The gate affects only the Backoffice console. | None. |
| No reminder e-mail arrived | The reminder is not enabled for your organisation, the recipient is suppressed, or the address is not an active admin or the nominated contact. | Check Status Reports for the contact. Ask your account team. |
| An unpaid-invoice reminder arrived late | Reminders are sent by a daily job at the 3, 7 and 14 day marks. | None. |
| The grace banner does not show | A package is active, package billing is not enforced, or no deadline is recorded. | Check the Billing status tab. |

## Related

- [Wallet, invoices and reports](https://noxtica.com/docs/billing/wallet-invoices-reports/): add funds, invoices and the report e-mails.
- [Plans, packages and add-ons](https://noxtica.com/docs/billing/plans-and-packages/): choose a package and read unavailability reasons.
- [Usage, quotas and metering](https://noxtica.com/docs/billing/usage-and-quotas/): quota status.
- [Audit log and data export](https://noxtica.com/docs/security/audit-log-and-exports/): reminder and billing events.
- [Terms of Service](https://noxtica.com/terms/): fees, billing and payment.

---

Source: https://noxtica.com/docs/compliance/overview/
Markdown: https://noxtica.com/docs/compliance/overview/index.md
Last updated: 2026-10-27

# Privacy and compliance controls in Backoffice

Backoffice keeps its privacy and legal controls in two sidebar groups: **Privacy & Legal** and **Web Analytics & Privacy**. Use this page as a map. It names each page, says who can open it, what it records and which docs page explains it. A security or privacy owner or a Backoffice administrator uses it to plan a review.

These pages record decisions and settings. They do not give legal advice, and a recorded setting does not make your use of Noxtica lawful. Your counsel decides that. The public legal pages are the sole source for legal terms: [Terms](https://noxtica.com/terms/), [Privacy Policy](https://noxtica.com/privacy/), [DPA](https://noxtica.com/dpa/), [Subprocessors](https://noxtica.com/subprocessors/), [Cookies](https://noxtica.com/cookies/), [Acceptable Use](https://noxtica.com/acceptable-use/), [Disclaimer](https://noxtica.com/disclaimer/) and [Legal notice](https://noxtica.com/legal-notice/).

## What it is

Availability: depends on your plan, role and the modules enabled for your organisation.

The sidebar shows both groups to administrators. A signed-in user with a lower role does not see the entries, and several pages also check a permission on the server. Changes to retention, raw IP storage, legal bases and per-domain consent ask for a fresh multi-factor check (step-up) before they save.

### Privacy & Legal

| Page | What it records or shows | Who can use it | Explained in |
| --- | --- | --- | --- |
| Data Retention | Days that browser intelligence data is kept, the check interval, a read-only retention schedule, a manual "Run retention now" action and the Raw IP storage opt-in. | Administrators. Saving needs step-up. | [Retention, raw IP and locations](https://noxtica.com/docs/compliance/retention-and-locations/) |
| Data Locations | Read-only table of where five kinds of your data are stored. | Administrators see the sidebar entry. The data is read-only. | [Retention, raw IP and locations](https://noxtica.com/docs/compliance/retention-and-locations/) |
| Compliance | Placeholder rows for compliance documents with disabled Download buttons, and an EU AI Act Article 50 transparency policy for verified AI agents when enabled for your organisation. | Administrators. | [DPA, sub-processors and assurance](https://noxtica.com/docs/compliance/assurance-and-subprocessors/) |
| Legal Basis Register | Versioned records of the legal basis your organisation asserts as controller for each gated feature, plus the per-domain Replay legal basis. | Administrators. Recording needs step-up. | [Legal basis register](https://noxtica.com/docs/compliance/legal-basis/) |
| Data Subject Scope | Read-only explanation of the decisions that belong to your visitors. Its links lead to controls that switch collection off or withdraw an assertion, never to a control that switches something on. | Administrators. | [Requests and deletion](https://noxtica.com/docs/compliance/requests-and-deletion/) |
| Sub-processors | Whether your organisation accepted the AI assistant as a sub-processor for write actions. | Administrators. | [DPA, sub-processors and assurance](https://noxtica.com/docs/compliance/assurance-and-subprocessors/) |
| Platform Assurances | Read-only statements of what Noxtica remains responsible for. Nothing to switch. | Administrators see it in the sidebar. | [DPA, sub-processors and assurance](https://noxtica.com/docs/compliance/assurance-and-subprocessors/) |

### Web Analytics & Privacy

| Page | What it records or shows | Who can use it | Explained in |
| --- | --- | --- | --- |
| Consent & Privacy | Per domain: the legal basis for real-user monitoring, whether visitors must consent, and the Do Not Track (DNT) and Global Privacy Control (GPC) policy. | Administrators. Saving needs step-up. | [Legal basis register](https://noxtica.com/docs/compliance/legal-basis/) and [Cookies and storage](https://noxtica.com/docs/compliance/cookies-and-storage/) |
| RUM Collection | Workspace switch for real-user monitoring and a sample rate per domain. | Administrators. | [Real user monitoring](https://noxtica.com/docs/observability/rum/) |
| Tracking Allowlists | Per domain: which custom events and properties are accepted and which origins may be traced. | Administrators. | [Custom events and tracing](https://noxtica.com/docs/observability/events-and-tracing/) |
| Capture Policies | Per domain: replay sampling, masking and retention, and console-log capture. | Administrators. | [Session replay](https://noxtica.com/docs/observability/session-replay/) and [Errors and console logs](https://noxtica.com/docs/observability/errors-and-source-maps/) |
| RUM Data Lifecycle | What real-user monitoring data you hold, the error-detail retention per domain, and a permanent purge per data lane. | Administrators. | [Retention, raw IP and locations](https://noxtica.com/docs/compliance/retention-and-locations/) |
| Uptime Checks | Scheduled HTTPS checks of endpoints you prove you own. | Administrators. | [Uptime checks and status](https://noxtica.com/docs/observability/uptime-alerts-status/) |

### Related pages outside these two groups

| Page | Where | What it is for | Explained in |
| --- | --- | --- | --- |
| Data Operations | Backoffice → Administration → Data Operations | Soft-delete end-user data, run retention now, remove admin accounts, read the operations history. | [Requests and deletion](https://noxtica.com/docs/compliance/requests-and-deletion/) |
| KYC Verifications and KYC Erasure Requests | Backoffice → Identity Verification → KYC Verifications and KYC Erasure | The two Backoffice routes that delete identity verification data: administrators delete verifications directly, and erasure requests are approved by a second administrator. | [Requests and deletion](https://noxtica.com/docs/compliance/requests-and-deletion/) and [Verification data](https://noxtica.com/docs/identity-verification-data/) |
| Legal basis for hosted verification | Backoffice → Identity Verification → KYC Invitations → Settings | Records the legal basis that hosted verification needs. | [Invitations and hosted settings](https://noxtica.com/docs/identity-verification-invitations/) |
| CSP & storage tab | Backoffice → Integrations & API → Script & Consent → CSP & storage | The cookie and storage table to copy into your cookie policy. | [Cookies and storage](https://noxtica.com/docs/compliance/cookies-and-storage/) |
| Privacy & cookies | Backoffice → Settings | Your own choice, as a signed-in user, whether Noxtica's consent-gated extensions run on the Backoffice console. | [Cookies and storage](https://noxtica.com/docs/compliance/cookies-and-storage/) |

Identity verification data follows a separate rule. Noxtica does not remove verification details or evidence by itself and sets no retention date for them. They stay until a tenant administrator deletes them. The Data Retention page applies to browser intelligence data and never touches verification records.

### Four separate legal-basis records

Backoffice keeps four kinds of recorded basis. A record of one kind never covers another.

| Record | Scope | Where you record it | What it gates |
| --- | --- | --- | --- |
| Register entry | Your workspace, one entry per gated feature | Privacy & Legal → Legal Basis Register | The gated feature named by the entry |
| Replay legal basis | One domain | Privacy & Legal → Legal Basis Register, section Replay legal basis | Turning on session replay for that domain |
| Consent & privacy decision | One domain | Web Analytics & Privacy → Consent & Privacy | Real-user monitoring, error-detail and console-log capture on that domain |
| Hosted verification legal basis | Your workspace | Identity Verification → KYC Invitations → Settings | Minting and submitting hosted verification sessions |

## Prerequisites

- A Backoffice account with the administrator role for your workspace. See [Roles and permissions](https://noxtica.com/docs/security/roles-and-permissions/).
- A multi-factor method enrolled on your account, because saving most of these pages asks for a fresh check. See [Sign-in and access](https://noxtica.com/docs/security/sign-in-and-access/).
- At least one domain added to the workspace for the per-domain pages. See [Domains](https://noxtica.com/docs/backoffice/domains/).
- Identity verification pages appear when the module is enabled for your organisation.

## Steps

### 1. Open the groups

Sign in at `https://backoffice.noxtica.com`. In the sidebar open **Privacy & Legal** and then **Web Analytics & Privacy**. If an entry is missing, your role is below administrator.

### 2. Set retention and raw IP storage

Open **Privacy & Legal → Data Retention**. Review the retention schedule and the Raw IP storage setting. Details are in [Retention, raw IP and locations](https://noxtica.com/docs/compliance/retention-and-locations/).

### 3. Record legal bases for the features you use

Open **Privacy & Legal → Legal Basis Register**. Record a basis for each gated feature you turn on, and record the Replay legal basis before you enable replay on a domain. Details are in [Legal basis register](https://noxtica.com/docs/compliance/legal-basis/).

### 4. Resolve per-domain consent decisions

Open **Web Analytics & Privacy → Consent & Privacy**. Decide the legal basis, the consent requirement and the DNT and GPC policy for each domain that collects real-user monitoring data.

### 5. Set capture policies

Open **Web Analytics & Privacy → Capture Policies**. Choose replay sampling, masking and retention and the console-log setting for each domain.

### 6. Publish your cookie disclosure

Open **Integrations & API → Script & Consent → CSP & storage**. Copy the storage table into your cookie policy. See [Cookies and storage](https://noxtica.com/docs/compliance/cookies-and-storage/).

### 7. Know your deletion and assurance routes

Read [Requests and deletion](https://noxtica.com/docs/compliance/requests-and-deletion/) and [DPA, sub-processors and assurance](https://noxtica.com/docs/compliance/assurance-and-subprocessors/) before a request or a procurement review arrives.

## Verify it works

- **Consent & Privacy** shows an "All resolved" badge and the line "No domain has an unresolved consent or privacy decision."
- **Legal Basis Register** shows the status "Asserted" and a receipt line for each basis you recorded.
- **Data Retention** lists the retention schedule with a Source badge for each row: "Your override", "Plan default" or "Default".
- **Raw IP storage** shows the badge "Disabled" or "Enabled" and the time of the last change.
- Every save above appears in the audit log. See [Audit log and data export](https://noxtica.com/docs/security/audit-log-and-exports/).

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| The Privacy & Legal group is missing from the sidebar. | The sidebar hides these entries from roles below administrator. | Ask an administrator of your workspace, or ask for the administrator role. |
| Legal Basis Register shows an error instead of the gates. | The register needs the permission to record legal bases, which is administrator level. | Sign in as an administrator. |
| A save asks you to verify again. | Retention, raw IP, legal basis and consent decisions need a fresh multi-factor check. | Complete the prompt. Cancelling changes nothing. |
| The Compliance page has Download buttons you cannot press. | The rows are placeholders. The tooltip says compliance documents will be provided through the customer success portal. | Ask your account team. Do not treat the rows as evidence that a report exists. |
| The EU AI Act card is missing from Compliance. | The card shows when the policy is enabled for your organisation. | Ask your account team whether it applies to you. |
| No identity verification retention note appears on Data Retention. | The note appears when the identity verification module is enabled for your organisation. | Enable the module through your account team. |

## Related

- [Legal basis register and receipts](https://noxtica.com/docs/compliance/legal-basis/): record, change and withdraw a legal basis.
- [Data retention, raw IP storage and data locations](https://noxtica.com/docs/compliance/retention-and-locations/): retention controls and where data lives.
- [Data subject scope, erasure requests and account deletion](https://noxtica.com/docs/compliance/requests-and-deletion/): deletion routes.
- [Cookies, storage and consent categories](https://noxtica.com/docs/compliance/cookies-and-storage/): what the SDK writes in a visitor's browser.
- [DPA, sub-processors, DPIA pointers and assurance](https://noxtica.com/docs/compliance/assurance-and-subprocessors/): public documents and assurance pointers.
- [Security and trust evidence](https://noxtica.com/docs/security/): what Noxtica publishes about its security posture.

---

Source: https://noxtica.com/docs/compliance/legal-basis/
Markdown: https://noxtica.com/docs/compliance/legal-basis/index.md
Last updated: 2026-10-27

# Legal basis register and receipts

Some Noxtica features stay off until your organisation records the legal basis it relies on. Backoffice keeps those records as receipts. A tenant administrator records, changes or withdraws a receipt. This page explains the register, the Replay legal basis, the per-domain consent decision and the errors you see when a receipt is missing.

A receipt is your organisation's statement as controller. It is not a record that any visitor consented, and it never replaces visitor consent. Noxtica does not tell you which basis to choose. Ask your counsel.

## What it is

Availability: depends on your plan, role and the modules enabled for your organisation.

The **Legal Basis Register** (Backoffice → Privacy & Legal → Legal Basis Register) lists each gated feature, called a gate. For each gate you see whether a basis is recorded ("Asserted" or "Not asserted"), the Article 6(1) basis, the Article 9(2) condition where one applies, the disclosure text you accepted, the receipt version and who recorded it.

Records are immutable and versioned:

- **Change basis** records a new version and keeps the previous one. A reason is required.
- **Withdraw** keeps the record with status "Withdrawn". A reason is required. Processing that relies on the basis stops.
- Nothing is deleted. Every action is logged with who did it, their role, the workspace and the time.

A Noxtica platform administrator can also record a basis for your workspace where that capability is enabled. The receipt then carries the actor role "superadmin", and your administrators can see it. It never substitutes for visitor consent.

Each receipt pins the exact disclosure text you read, by version, language and a digest. The register shows that text unchanged. If no disclosure is published in your current language, the register refuses to record a basis and does not fall back to another language.

### Gates in the register

Register entries use these labels. "Required" means Backoffice asks for an Article 9(2) condition. "Optional" means the dialog offers a condition for use when special-category data is in scope. Whenever you assert a condition you also type the gate key to confirm it.

| Register entry | Article 9(2) condition | Note |
| --- | --- | --- |
| Investigations module | Optional | Also covers Related Devices. |
| Assistant write actions | Optional | The sub-processor acceptance for the AI assistant. |
| Granular sub-fingerprint axes | Not accepted | Article 6(1) is limited to legitimate interests. |
| Behavioral tracks (pointer/touch) | Required | |
| JA4H HTTP fingerprinting | Required | |
| Behavioral baseline | Required | |
| Fingerprinting: CSS system colours & fonts | Required | Fixed 365-day term. |
| Fingerprinting: font enumeration | Optional | Fixed 365-day term. |
| Fingerprinting: window-key litter | Optional | Fixed 365-day term. |
| Fingerprinting: emoji geometry | Optional | Fixed 365-day term. |
| APM and host telemetry ingest | Optional | APM is In development. New Ingestion API keys are bound to the receipt. |
| KYC raw evidence storage | Optional | Identity verification. |
| KYC behavioral capture | Optional | Identity verification. |
| KYC delegation | Optional | Identity verification. |
| KYC voice profiling | Required | Identity verification. Takes effect when the platform switch is also on. |
| KYC age and gender estimation | Required | Identity verification. Takes effect when the platform switch is also on. |

The register shows the expiry date of a receipt that has a fixed 365-day term. Which entries appear depends on what is enabled for your organisation.

### Features that refuse to start without a receipt

| Feature | What you see without a receipt |
| --- | --- |
| Session replay on a domain | Enabling replay is refused with `replay_receipt_required`. |
| Looser replay masking on a domain | The change is refused with the same error, even on a disabled policy. |
| Hosted identity verification | Minting or submitting a hosted session is refused with `kyc_legal_basis_receipt_required` (HTTP 403). |
| Investigations and Related Devices | The module reads as off and the Related Devices page says it needs a recorded lawful basis. |
| Granular sub-fingerprint axes | The values are not persisted until an active legitimate-interests receipt exists. |
| APM ingestion keys (In development) | Creating a key is refused with `apm_legal_basis_required` until a receipt exists. |
| Console-log and error-detail capture | Capture stays off until the domain records a legal basis or requires visitor consent. |

Other register entries record your basis. This page does not claim that every entry blocks a feature.

### Per-domain Replay legal basis

Replay has its own receipt on the same page, in the section **Replay legal basis**. It is recorded per domain with a legal basis reference, which is your DPA or DPIA reference. A tenant administrator alone can record it. A Noxtica platform administrator cannot record it for you. Recording does not turn replay on. You turn replay on in **Web Analytics & Privacy → Capture Policies**.

### Per-domain consent decision

**Web Analytics & Privacy → Consent & Privacy** records, for each domain, the legal basis for real-user monitoring, whether visitors must consent and the DNT and GPC policy. The Legal basis list offers "— none —" and `rum_observability`. A domain appears in the list when it collects real-user monitoring data, has no legal basis recorded and either does not require consent or overrides DNT and GPC.

## Prerequisites

- The administrator role. Reading the register needs the same permission as recording a basis.
- A multi-factor method enrolled on your account. Recording, changing, withdrawing and saving a consent decision ask for a fresh check.
- The decision itself. Settle with your counsel which Article 6(1) basis and, where relevant, which Article 9(2) condition apply to the feature.
- For hosted identity verification, the basis is recorded on a different page. See [Invitations and hosted settings](https://noxtica.com/docs/identity-verification-invitations/).
- Replay legal basis is the exception to platform-administrator recording: your own tenant administrator must record it.

## Steps

### 1. Record a basis for a gate

1. Open Backoffice → Privacy & Legal → Legal Basis Register.
2. Pick the gate and select **Read the disclosure**. Read it.
3. Select **Record basis**.
4. Choose the **Article 6(1) lawful basis**. Choose an **Article 9(2) condition** when the gate shows "Art. 9 special category" or the dialog marks it required.
5. If you chose an Article 9(2) condition, type the gate key to confirm the special-category assertion.
6. Tick the acknowledgement: "I have read the disclosure above and I am recording this lawful basis on behalf of my organisation as controller."
7. Submit and complete the step-up check.

### 2. Change or withdraw a basis

1. On the gate, select **Change basis** or **Withdraw**.
2. Enter the reason. The limit is 500 characters.
3. For a change, choose the new basis and acknowledge the current disclosure. When a newer disclosure was published, processing that depends on the newer text stays off until you do.
4. Select **History** to see every version with its status, bases, actor, role, times and reasons.

### 3. Record the Replay legal basis

1. In the same page, scroll to **Replay legal basis**.
2. Select the domain.
3. Enter the real DPA or DPIA reference in **Legal basis reference (DPA / DPIA)**.
4. Read the disclosure, tick the acknowledgement and select **Record legal basis**.
5. To change it later choose **Replace the active basis**. To stop replay capture on that domain choose **Revoke the active basis**.
6. Turn replay on in Web Analytics & Privacy → Capture Policies.

A reference that is empty or contains the text "not supplied" counts as a placeholder. While the reference is a placeholder, Backoffice refuses to arm replay or loosen masking when the result uses masking looser than strict or turns off required consent.

### 4. Decide a domain's consent and DNT/GPC policy

1. Open Web Analytics & Privacy → Consent & Privacy. Domains that still need a decision are listed.
2. Choose the **Legal basis** or leave it as "— none —".
3. Turn **Requires consent** on or off. Without a legal basis, you must require consent.
4. Choose the **DNT/GPC policy**: **Honor** or **Documented override**. A documented override needs the legal basis and the acknowledgement "I acknowledge this domain overrides DNT/GPC on an approved legal basis."
5. Select **Save decision** and complete the step-up check. The domain leaves the list.

## Verify it works

- The gate shows "Asserted" with a receipt line such as "Article 6(1): … · receipt v1 · recorded by …".
- **History** lists the new version, and a withdrawn version shows "Withdrawn" with your reason.
- The audit log shows `tenant_legal_basis_asserted`, `tenant_legal_basis_superseded` or `tenant_legal_basis_revoked`. A consent decision shows `domain_rum_privacy_updated`.
- With a receipt in place, enabling replay on the domain is no longer refused for a missing receipt. Without one, Backoffice answers that no active session_replay legal-basis receipt exists for the domain and that nothing was changed.
- **Consent & Privacy** shows "No domain has an unresolved consent or privacy decision."

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| Enabling replay fails with `replay_receipt_required`. | No active Replay legal basis exists for the domain. | Record it in Legal Basis Register → Replay legal basis, then enable replay again. |
| Replay save fails with `legal_basis_placeholder` (HTTP 409). | The active reference is empty or says "not supplied". | Replace the active basis with the real DPA or DPIA reference. |
| Replay save fails with `replay_receipt_validation_unavailable` (HTTP 503). | The receipt check could not be completed. Nothing changed. | Retry later. |
| Record basis is blocked with a message about the disclosure. | No disclosure is published in your language, or its digest does not match. | Switch the Backoffice language to one with a published disclosure. If the digest message persists, report it. |
| Recording is refused with `asserting_role_required` (HTTP 403). | Your role is neither tenant administrator nor platform administrator. | Ask a tenant administrator of your workspace to record it. |
| Recording fails with `already_active` (HTTP 409). | A basis is already active for the gate. | Use **Change basis**. |
| Recording fails with `disclosure_mismatch` (HTTP 409). | The page you loaded is stale or the text changed. | Reload and record again. Nothing was recorded. |
| The consent decision is rejected: "Choose a legal basis, or turn on Requires consent." | Capturing without consent needs an approved basis. | Choose `rum_observability` or turn on Requires consent. |
| The consent decision is rejected for a documented override. | An override needs a legal basis and the acknowledgement. | Choose the basis, tick the acknowledgement, or set the policy back to Honor. |
| Hosted verification returns `kyc_legal_basis_receipt_required`. | No active hosted-capture basis exists for your organisation. | Record it under KYC Invitations → Settings. |

## Related

- [Privacy and compliance controls in Backoffice](https://noxtica.com/docs/compliance/overview/): map of every privacy page.
- [Cookies, storage and consent categories](https://noxtica.com/docs/compliance/cookies-and-storage/): DNT and GPC behaviour and consent categories.
- [Session replay](https://noxtica.com/docs/observability/session-replay/): arm replay after you record the basis.
- [Invitations and hosted settings](https://noxtica.com/docs/identity-verification-invitations/): the hosted verification legal basis.
- [Audit log and data export](https://noxtica.com/docs/security/audit-log-and-exports/): find who recorded what.
- [Privacy Policy](https://noxtica.com/privacy/) and [DPA](https://noxtica.com/dpa/): the public legal documents.

---

Source: https://noxtica.com/docs/compliance/retention-and-locations/
Markdown: https://noxtica.com/docs/compliance/retention-and-locations/index.md
Last updated: 2026-10-27

# Data retention, raw IP storage and data locations

An administrator uses three Backoffice pages to control and read how Noxtica stores data for the workspace: **Data Retention**, which includes the Raw IP storage opt-in, **Data Locations** and **RUM Data Lifecycle**. This page explains each control, what it changes and what to check afterwards.

The controls here apply to browser intelligence data and real-user monitoring data. Identity verification data follows a separate rule at the end of this page.

## What it is

Availability: depends on your plan, role and the modules enabled for your organisation.

### Data Retention

Open Backoffice → Privacy & Legal → Data Retention. The page has four parts.

| Part | What it does |
| --- | --- |
| Data policy | Two settings: **Data retention (days)**, "how long to keep browser intelligence data", and **Check interval (days)**, "minimum days between full re-collection per device". |
| Retention schedule | A read-only table of the effective window for each data category, with a Source badge. |
| Run retention now | An on-demand sweep that applies the saved window to your workspace. |
| Raw IP storage | An opt-in to store the full client IP address alongside the hashed one. |

The Backoffice accepts 1 to 365 days for **Data retention (days)** and 1 to 30 days for **Check interval (days)**. Every package starts at 7 days for **Data retention (days)**. The values in force and the plan defaults are shown in Backoffice and can change.

The retention schedule lists two categories:

| Category | Window comes from |
| --- | --- |
| Detection events | Your saved retention days ("Your override"), else the plan ("Plan default"), else "Default". |
| Audit log | The plan ("Plan default"). You cannot override it. |

The check interval controls how often a device is fully re-collected. It does not set how often data is removed. The purge job runs daily and you cannot configure it. Backoffice states that automated export before purge is not wired in this view. To archive data before it is removed, use the export tools. See [Audit log and data export](https://noxtica.com/docs/security/audit-log-and-exports/). Plan retention by data class is described on [Pricing](https://noxtica.com/pricing/).

For detection events, removal by retention is a soft delete. Records older than the window are hidden from views and exports. Permanent removal is a separate step that a Noxtica platform administrator performs. This page gives no timeline for it.

Some removal steps, such as audit-log removal and deletion of stored replay objects, can be paused platform-wide while Noxtica reviews its erasure safeguards. Backoffice does not show that state, and the schedule shows the window that applies, not whether a step is running now. If a window matters to your policy, ask your account team.

### Raw IP storage

By default Noxtica keeps a hashed IP and stores no raw IP. When you opt in, it also stores the raw client IP address so the operator console can search and correlate by exact IP during fraud investigations. The raw IP is purged on the same retention schedule as the rest of the submission data.

The raw IP is personal data. Backoffice warns you to enable it where your data processing agreement authorizes raw IP retention for fraud investigation and where your lawful basis and storage limitation are documented. Ask your counsel.

Turning the setting off permanently deletes every raw IP already stored for your workspace. The result message reports how many stored fingerprint records were cleared. This cannot be undone.

### Data Locations

Open Backoffice → Privacy & Legal → Data Locations. The table is read-only and shows five kinds of data. Each row has these columns.

| Column | What it shows |
| --- | --- |
| Service | Event data, Event payloads, Metrics, Warehouse analytics or KYC evidence. A "platform default" note means no location was chosen for your workspace. |
| Provider & region | The store and the location name, for example a Cloudflare or GCP store. |
| Jurisdiction | EU, US or TR jurisdiction, or "jurisdiction not assigned". |
| Retention | "retained N days" for the row. |
| Usage | A counted or estimated size with an "as of" time, "not applicable — this class has no usage meter", or a message that the figure cannot be read yet, with a reason. |

You cannot change a location from Backoffice. A Noxtica platform administrator sets placement. If you have a location requirement, ask your account team. The page shows what is configured. It is not a residency commitment, and your contract and the [DPA](https://noxtica.com/dpa/) are the source for commitments.

The Retention figure on the KYC evidence row is not a deletion date. Noxtica does not remove verification details or evidence by itself.

### RUM Data Lifecycle

Open Backoffice → Web Analytics & Privacy → RUM Data Lifecycle. It lists each real-user monitoring lane that can be purged on demand, what is stored and its current window. You can set the error-detail retention for a domain from 1 to 90 days and start a permanent purge of a lane. A purge needs a typed confirmation phrase and a fresh step-up check, and it cannot be undone. Replay retention is set per domain in Capture Policies, from 1 to 90 days.

The default window is 7 days on every package for error details, console logs, replay recordings and APM data. Error details, console log lines and APM data are held in the analytics warehouse, which removes them after 7 days: you can shorten their window but not extend it. Base RUM counters are platform-managed, kept for up to three months and not configurable.

### Identity verification data

Verification details and evidence are not part of these schedules. The Data Retention page covers browser intelligence data and never touches verification records. When the identity verification module is enabled, the page shows a note that these records are retained until a tenant administrator deletes them, with a link to KYC Erasure Requests. An administrator deletes verifications in KYC Verifications and works erasure requests in KYC Erasure. See [Requests and deletion](https://noxtica.com/docs/compliance/requests-and-deletion/).

## Prerequisites

- The administrator role. Saving retention needs the settings permission.
- A multi-factor method on your account. Saving retention, saving the raw IP setting, running retention now and purging RUM data ask for a fresh check.
- For raw IP storage, a documented decision from your privacy owner. The setting is off by default.
- For Data Locations, nothing beyond access to the page.

## Steps

### 1. Set the retention window

1. Open Backoffice → Privacy & Legal → Data Retention.
2. Enter **Data retention (days)** from 1 to 365 and **Check interval (days)** from 1 to 30.
3. Select **Save settings** and complete the step-up check.
4. If you shortened the window, confirm "Shorten data retention?". Data older than the new window becomes eligible for soft deletion at the next retention run.

### 2. Run retention now (optional)

1. Under **Run retention now**, select **Run retention now**.
2. Confirm. The run applies the saved window and cannot delete anything the schedule would keep.
3. Read the result. It lists soft-deleted fingerprints, events, visits, tracker batches and tracker metrics, and a section "What this run could NOT reach".

A workspace can start 4 runs in one hour. A run already in progress blocks a new one.

### 3. Decide raw IP storage

1. In the same page, find **Raw IP storage (opt-in)**.
2. Read the warning and the badge, which shows "Disabled" or "Enabled".
3. Move the toggle and select **Save**. Complete the step-up check.
4. When turning it off, read "Turning this off will permanently delete every raw IP already stored for this tenant." before you save.

### 4. Read your data locations

1. Open Backoffice → Privacy & Legal → Data Locations.
2. Read each row. Note any row marked "platform default".
3. Send questions about placement to your account team.

### 5. Set error-detail retention for a domain

1. Open Backoffice → Web Analytics & Privacy → RUM Data Lifecycle.
2. Select the domain.
3. Enter **Retention (days, 1–90)** and save.

## Verify it works

- The retention schedule shows your days for Detection events with the "Your override" badge.
- The audit log shows `settings_updated` with the new values.
- After a run, the history on Data Operations shows a "Retention run" with a status. See [Requests and deletion](https://noxtica.com/docs/compliance/requests-and-deletion/).
- Raw IP storage shows the new badge. The audit log shows `raw_ip_storage_enabled` or `raw_ip_storage_disabled`. When you turn it off, the audit entry records the number of scrubbed records and never the IP values.
- Data Locations lists five rows with a provider and region on each.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| Save shows "Enter a value between 1 and 365." | The retention value is outside the accepted range. | Enter a whole number from 1 to 365. The check interval accepts 1 to 30. |
| Save asks you to verify again. | Saving retention needs a fresh multi-factor check. | Complete the prompt. |
| The retention schedule is missing. | The schedule is fail-soft. A failed read hides the panel without affecting the form. | Reload the page. |
| Run retention now answers "A retention run is already in progress for this workspace." | A run started in the last 30 minutes is still running. | Wait for it to finish. |
| Run retention now answers "Too many manual retention runs. Try again later." | The limit of 4 runs per hour was reached. | Try again after the hour passes. |
| The result says the run was a PARTIAL run or lists data it could not reach. | The run stopped early or could not reach some stores. | Treat the run as incomplete. Run it again later and read the unreachable list. |
| The audit log retention cannot be edited. | The audit log window comes from your plan. | Ask your account team. |
| A Data Locations row says its usage cannot be read yet. | The usage meter is not ready or the read failed. | Reload later. The location and jurisdiction columns still apply. |
| A raw IP opt-out reports zero cleared records. | No raw IP was stored for the workspace. | No action needed. |

## Related

- [Privacy and compliance controls in Backoffice](https://noxtica.com/docs/compliance/overview/): map of every privacy page.
- [Data subject scope, erasure requests and account deletion](https://noxtica.com/docs/compliance/requests-and-deletion/): delete end-user data on demand.
- [Session replay](https://noxtica.com/docs/observability/session-replay/): replay sampling, masking and retention.
- [Audit log and data export](https://noxtica.com/docs/security/audit-log-and-exports/): export data before it is removed.
- [Privacy Policy](https://noxtica.com/privacy/), [DPA](https://noxtica.com/dpa/) and [Subprocessors](https://noxtica.com/subprocessors/): the public legal documents.

---

Source: https://noxtica.com/docs/compliance/requests-and-deletion/
Markdown: https://noxtica.com/docs/compliance/requests-and-deletion/index.md
Last updated: 2026-10-27

# Data subject scope, erasure requests and account deletion

When one of your visitors or users asks for their data to be deleted, a tenant administrator works through the tools on this page. Backoffice has separate routes for browser intelligence data, identity verification data, administrator accounts and your Noxtica account. This page names each route, who runs it and what it leaves untouched.

Backoffice does not decide whether a request is valid and does not give legal advice. You verify the requester and decide the response with your counsel.

## What it is

Availability: depends on your plan, role and the modules enabled for your organisation.

| Route | What it removes | Who runs it |
| --- | --- | --- |
| Data Operations → End-user data | Soft-deletes fingerprints, events and visits for devices or an external user ID. | Tenant administrator, with step-up. |
| KYC Verifications → Delete | Identity verifications you select, with their evidence files. | Tenant administrator, with a reason, a typed confirmation phrase and step-up. |
| KYC Erasure Requests | Identity verification data for a verification subject. | A request is opened for the subject. A different tenant administrator approves it in Backoffice, with step-up. |
| Data Operations → Admin accounts | Soft-deletes a Backoffice administrator account. | Tenant administrator, with step-up. |
| Server API for behavioral baselines | Erases a subject's behavioral baseline, when the module is enabled for your organisation. | Your server, with an API key that has the erase scope. |
| Delete your Noxtica account form | Starts a reviewed account deletion request from the account email. | The account owner. |

Backoffice has no screen that assembles a per-person access report. To answer an access request, use the export tools described in [Audit log and data export](https://noxtica.com/docs/security/audit-log-and-exports/).

### Data Subject Scope

Open Backoffice → Privacy & Legal → Data Subject Scope. The page is read-only. It explains a boundary: your organisation can record its own lawful basis as controller, but it can never supply a visitor's consent. Consent belongs to the visitor.

Three cards explain what that means.

| Card | What it says | Link on the card |
| --- | --- | --- |
| Session replay | Your organisation can stop recording per domain at any time. It cannot declare that a visitor consented to being recorded. | Turn recording off in Replay policy |
| Per-domain consent and DNT/GPC | Each domain records whether consent is required and whether DNT and GPC signals are honored. Overriding a signal needs a recorded lawful basis and is never the visitor's consent. | Review per-domain decisions |
| Behavioural and biometric signals | Collection can be turned off in each signal's own section, and a recorded assertion can be withdrawn in one click. | Withdraw an assertion in the Legal basis register |

Everything reachable from the page turns collection off or withdraws an assertion. Turning something on is not offered. Recording "consent is not required" for a domain is a controller statement that another lawful basis applies. It is never a record that consent was obtained.

### End-user soft delete in Data Operations

Data Operations soft-deletes browser intelligence data. The records are hidden from views and exports. Permanent removal is a separate step that a Noxtica platform administrator performs, and this page gives no timeline for it. The operation reports fingerprints, events and visits. Every operation is audited and listed in the History tab.

Erasure can be paused platform-wide while Noxtica reviews its safeguards. While it is paused, the end-user delete is refused with HTTP 503, a one-hour `Retry-After` and the message "Customer data erasure is temporarily on hold while its safeguards are reviewed." Backoffice does not show whether the pause is on. Ask your account team.

### Identity verification data

Identity verification data is separate. Noxtica does not remove verification details or evidence by itself and sets no retention date for them. They stay until a tenant administrator deletes them. Backoffice has two routes that delete them: **Delete verification** and **Delete selected** in KYC Verifications, and KYC Erasure Requests.

Delete verification removes the verifications an administrator selects (up to 25 at a time) together with their evidence files. The administrator gives a reason of 3 to 500 characters, types a confirmation phrase such as `delete 2 verifications permanently` and completes step-up. Billing usage records, legal-basis receipts and the audit trail are kept, two audit entries record the delete, and a legal hold or an open erasure request blocks it. No server API key can delete a verification. Business (KYB) and merchant (KYM) items are erased from their own pages with a reason. The full steps are in [Verification data](https://noxtica.com/docs/identity-verification-data/).

A right-to-erasure request is opened for a verification subject, and Backoffice lists it with the name of the requester. A different administrator approves it. Approving your own request is refused. A request can be placed on legal hold, which stops it from proceeding to deletion until the hold is released. When a request completes, Noxtica sends the `kyc.erasure.completed` event to your webhooks. It is not sent for a partial result and carries no subject identifier, and deleting verifications directly does not send it. Execution depends on what is enabled for your organisation. How a request is opened, its reach and its limits are in [Verification data](https://noxtica.com/docs/identity-verification-data/).

### Admin accounts and your Noxtica account

Removing an administrator in Data Operations soft-deletes the account. The user loses access at once and disappears from lists. You cannot remove your own account, and the last active administrator cannot be removed. Backoffice has no screen that deletes a workspace. To close a workspace, contact your account team. Your contract and the [DPA](https://noxtica.com/dpa/) govern what happens to customer data after termination.

The public form at [Delete your Noxtica account](https://noxtica.com/account-deletion/) starts a reviewed deletion request for a Noxtica account. You enter the account email, receive a one-time verification code, enter it and submit. The page lists what may be retained. Read it before you submit.

## Prerequisites

- The administrator role and a multi-factor method. Data Operations asks for a fresh check before it runs an operation.
- For an end-user delete, a list of device IDs, up to 500 per operation, or an external user ID. A date range or a domain narrows the match.
- For Delete verification, the administrator role, a fresh step-up check and the identity verification module enabled for your organisation.
- For KYC Erasure Requests, the identity verification module enabled for your organisation and an administrator other than the requester to approve.
- For the behavioral baseline API, a server API key with the erase scope and the module enabled. See [API reference](https://noxtica.com/docs/api/reference/).
- For the account deletion form, access to the email address of the account.

## Steps

### 1. Review the data subject boundary

Open Privacy & Legal → Data Subject Scope. Read the three cards. Use the links to switch off collection that depends on a visitor's decision.

### 2. Soft-delete end-user data

1. Open Backoffice → Administration → Data Operations and select **End-user data**.
2. Enter **Device IDs (one per line)** or an **External user ID (optional)**. You can add a **Domain (optional)**, **From date** and **To date**.
3. Add a **Reason (optional)**, up to 280 characters. It is stored in the audit log. Use a reference such as your request number.
4. Select **Preview impact**. Read the estimated fingerprints, events and visits. The preview is a dry run.
5. Select **Proceed with soft delete**.
6. Type `DELETE` and select **Confirm soft delete**. Complete the step-up check.
7. Read the banner "Soft-deleted: … fingerprints, … events, … visits".

### 3. Delete identity verification data

To delete verifications you choose:

1. Open Backoffice → Identity Verification → KYC Verifications.
2. Open a case and select **Delete verification**, or tick the rows and select **Delete selected** (up to 25).
3. Enter a reason of 3 to 500 characters, type the confirmation phrase the dialog shows, select **Delete permanently** and complete the step-up check.

To work an erasure request:

1. Open Backoffice → Identity Verification → KYC Erasure.
2. Find the request in the list. The Requested by column names who opened it. Requests appear after a subject or an operator submits one for your workspace.
3. As an administrator other than the requester, select **Approve** and confirm. Complete the step-up check.
4. If a legal hold applies, select **Hold**. Select **Release hold** when it ends.
5. Watch the status column until the request completes. Select **View items** to see per-artifact progress.
6. Subscribe a webhook to the KYC erasure completed event to receive the completion signal. See [Identity verification events](https://noxtica.com/docs/identity-verification-webhooks/).

### 4. Remove an administrator account

1. Open Data Operations and select **Admin accounts**.
2. Select the user, add a reason and confirm with `DELETE` and the step-up check.

### 5. Request deletion of a Noxtica account

1. Open [Delete your Noxtica account](https://noxtica.com/account-deletion/).
2. Enter the account email and select **Send verification code**.
3. Enter the code from the email and select **Submit deletion request**.

## Verify it works

- The preview shows "Dry run · no data deleted yet" before you confirm anything.
- After confirmation the History tab shows an "End-user delete" row with a status of Completed. A "PARTIAL run" banner means the row limit was reached and you must run it again with tighter filters.
- The audit log records approvals and refusals of an erasure request. An end-user delete shows `data_ops_end_user_delete` with the reason. A verification delete shows `kyc_verification_delete_requested` and `kyc_verification_deleted` with the reason.
- A deleted verification no longer appears in KYC Verifications.
- A KYC erasure request moves from requested to authority verified after a different administrator approves it. It ends as completed or partial.
- The account deletion page answers "Your account deletion request has been accepted for review."

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| The end-user delete fails with HTTP 503 and "Customer data erasure is temporarily on hold while its safeguards are reviewed." | Erasure is paused platform-wide. | Ask your account team. Retry after the pause is lifted. |
| The delete is refused because no subject identifier was given. | A delete needs a device ID list or an external user ID. A date range or a domain alone is not enough, although the preview accepts them. | Add device IDs or an external user ID. |
| "Too many device IDs" appears. | The list exceeds 500 entries. | Split the list into several operations. |
| The external user ID matches too many devices. | The match exceeded the limit of 10,000 devices. | Narrow the date range. |
| A PARTIAL run is reported. | The operation hit the row limit for some tables. | Re-run with tighter filters, as the banner says. |
| Approve is refused with "You cannot approve your own erasure request — a different admin must approve it." | Dual control requires an approver other than the requester. | Ask another administrator to approve. |
| The KYC Erasure page says the KYC module is not enabled. | The identity verification module is not enabled for your organisation. | Ask your account team. |
| Delete verification is refused with "Blocked by a legal hold or an open erasure request." | A legal hold is in place in your tenant, or an erasure request for the same subject is still open. | Release the hold or let the request finish, then delete again. |
| "Cannot remove the last active admin." | A workspace must keep one active administrator. | Add another administrator, then remove the account. |
| The account deletion form says too many attempts. | The form limits repeated attempts. | Wait a while and try again. |

## Related

- [Privacy and compliance controls in Backoffice](https://noxtica.com/docs/compliance/overview/): map of every privacy page.
- [Data retention, raw IP storage and data locations](https://noxtica.com/docs/compliance/retention-and-locations/): scheduled removal of browser intelligence data.
- [Verification data](https://noxtica.com/docs/identity-verification-data/): identity verification data storage, access and deletion.
- [Identity verification events](https://noxtica.com/docs/identity-verification-webhooks/): the erasure completed event.
- [Audit log and data export](https://noxtica.com/docs/security/audit-log-and-exports/): export data and find who ran an operation.
- [Privacy Policy](https://noxtica.com/privacy/) and [DPA](https://noxtica.com/dpa/): the public legal documents.

---

Source: https://noxtica.com/docs/compliance/assurance-and-subprocessors/
Markdown: https://noxtica.com/docs/compliance/assurance-and-subprocessors/index.md
Last updated: 2026-10-27

# DPA, sub-processors, DPIA pointers and assurance

A procurement, security or privacy reviewer uses this page to find what Noxtica provides for a vendor review. It points to the public documents, explains the sub-processor and assurance pages inside Backoffice, and says where to ask for support material that is not public.

This page does not summarise the legal documents and does not describe the terms they contain. Read the documents themselves. It also does not restate what independent assurance exists. The [Security and trust evidence](https://noxtica.com/docs/security/) page states that.

## What it is

Availability: depends on your plan, role and the modules enabled for your organisation.

### Public documents

| Document | Where |
| --- | --- |
| Data Processing Agreement | [DPA](https://noxtica.com/dpa/) |
| Sub-processor list | [Subprocessors](https://noxtica.com/subprocessors/) |
| Privacy Policy | [Privacy Policy](https://noxtica.com/privacy/) |
| Terms | [Terms](https://noxtica.com/terms/) |
| Cookies | [Cookies](https://noxtica.com/cookies/) |
| Acceptable Use | [Acceptable Use](https://noxtica.com/acceptable-use/) |
| Disclaimer | [Disclaimer](https://noxtica.com/disclaimer/) |
| Legal notice | [Legal notice](https://noxtica.com/legal-notice/) |

Backoffice also serves a copy of each document inside the console: Terms, Privacy, Cookies, Acceptable Use, Legal notice, Subprocessors, Disclaimer and DPA. When Noxtica publishes a new edition of a document that users accept, Backoffice can ask each user to accept it again. The re-acceptance prompt covers Terms, Privacy, Acceptable Use, Disclaimer and DPA.

### Sub-processors in Backoffice

Open Backoffice → Privacy & Legal → Sub-processors. The page covers one relationship: the Noxtica AI assistant acting as a sub-processor when it makes changes inside your workspace. The page states that this follows your organisation accepting the relationship and recording a lawful basis for it. The acceptance is a signed receipt, not a toggle.

The page shows the status "Accepted" or "Not accepted". When accepted, it shows a line such as "Article 6(1): … · receipt v… · recorded by …". You record, change or revoke the acceptance in the Legal Basis Register under the entry "Assistant write actions". Revoking takes effect at once and does not ask for a basis again. The page also links to the full sub-processor list. For the public list, use [Subprocessors](https://noxtica.com/subprocessors/).

### Platform Assurances

Open Backoffice → Privacy & Legal → Platform Assurances. The page is read-only and has nothing to switch, accept or request. It names five categories that the platform keeps responsibility for:

| Category | Title on the page |
| --- | --- |
| Shared security | Security enforcement shared by every tenant |
| Infrastructure | Platform-wide infrastructure |
| Visitors | Protections owed to your visitors |
| Cross-tenant detection | Cross-tenant detection and intelligence |
| Licences | Third-party licences and contracts |

The page links to the Privacy Policy, the sub-processor list and the Terms of service for the contractual side.

### Compliance page

Open Backoffice → Privacy & Legal → Compliance. The page shows placeholder rows for compliance documents. Their Download buttons are disabled, and the tooltip says compliance documents will be available through the customer success portal. The rows are not evidence that a report exists. When the EU AI Act policy is enabled for your organisation, the page also shows the Article 50 transparency disclosure policy for verified AI agents. It is observe-only: you choose "Shadow (observe only)" or "Dry-run (preview template)", and no disclosure is injected into responses.

### DPIA support

This documentation set links no DPIA. Ask your account team for DPIA support material. When you turn on session replay, Backoffice asks you to enter the real DPA or DPIA reference for your own assessment. See [Legal basis register and receipts](https://noxtica.com/docs/compliance/legal-basis/).

### Security posture, vulnerability reports and status

- The [Security and trust evidence](https://noxtica.com/docs/security/) page lists what Noxtica publishes about controls, cryptography boundaries and module data scope.
- Vulnerability reports go to the contact named in the file `/.well-known/security.txt` on `noxtica.com`. The file has an `Expires` field. Check that the date has not passed before you rely on the file.
- Service state is at `https://status.noxtica.com`. The status page is not a contractual SLA. See [Uptime checks and status](https://noxtica.com/docs/observability/uptime-alerts-status/).
- Request procurement material for the exact service and deployment you review through [Contact](https://noxtica.com/contact/?topic=security).

### Which route answers which question

| You need | Go to |
| --- | --- |
| The processing agreement and the sub-processor list | [DPA](https://noxtica.com/dpa/) and [Subprocessors](https://noxtica.com/subprocessors/) |
| To record or revoke the AI assistant acceptance | Backoffice → Privacy & Legal → Sub-processors, then the Legal Basis Register |
| A statement of what Noxtica keeps responsibility for | Backoffice → Privacy & Legal → Platform Assurances |
| DPIA support material | Your account team |
| Security and procurement material for a named service | [Contact](https://noxtica.com/contact/?topic=security) |
| Public security evidence | [Security and trust evidence](https://noxtica.com/docs/security/) |
| To report a vulnerability | The contact in `/.well-known/security.txt` |
| Current service state | `https://status.noxtica.com` |

## Prerequisites

- For the sub-processor acceptance, the administrator role and a multi-factor method. Recording a basis asks for a fresh check.
- A decision from your counsel on whether and on which basis your organisation accepts the AI assistant for write actions. Write actions apply when the assistant is enabled for your organisation.
- For procurement material, the name of the service, the modules and the deployment you review.

## Steps

### 1. Collect the public documents

Open [DPA](https://noxtica.com/dpa/), [Subprocessors](https://noxtica.com/subprocessors/), [Privacy Policy](https://noxtica.com/privacy/) and [Terms](https://noxtica.com/terms/). Add the version you reviewed and the date to your vendor record.

### 2. Decide on the AI assistant

1. Open Backoffice → Privacy & Legal → Sub-processors.
2. Read the status, "Accepted" or "Not accepted".
3. To accept, select **Record the acceptance in the Legal basis register**. Read the disclosure, choose the Article 6(1) basis, tick the acknowledgement and submit. See [Legal basis register and receipts](https://noxtica.com/docs/compliance/legal-basis/).

### 3. Review what Noxtica keeps responsibility for

Open Backoffice → Privacy & Legal → Platform Assurances. Read the five categories. Record the page in your vendor review as a statement, not a control.

### 4. Ask for DPIA and procurement support

Send a request through [Contact](https://noxtica.com/contact/?topic=security) or to your account team. Name the service and modules you review and the questions you need answered.

### 5. Register the vulnerability contact

Open `/.well-known/security.txt` on `noxtica.com`. Copy the contact and check the `Expires` date. Add the status page to your monitoring tools.

## Verify it works

- Sub-processors shows "Accepted" with a receipt line, or "Not accepted" before you record one.
- The Legal Basis Register entry "Assistant write actions" shows "Asserted" and the same receipt version.
- The audit log shows `tenant_legal_basis_asserted` for the acceptance and `tenant_legal_basis_revoked` after a revocation.
- The public documents open at the addresses above.
- Platform Assurances lists the five categories and shows no control.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| The Sub-processors page is missing from the sidebar. | The sidebar hides it from roles below administrator. | Ask an administrator. |
| The page shows an error instead of the status. | The status needs the permission to read legal-basis records, which is administrator level. | Sign in as an administrator. |
| Record the acceptance is blocked with a message about the disclosure. | No disclosure is published in your language, or its digest does not match. | Switch the Backoffice language to one with a published disclosure. |
| Revoking does not ask for a basis. | Revoking is the cheap direction by design. It asks for a reason and takes effect at once. | Enter the reason. |
| The Compliance page Download buttons do nothing. | The rows are disabled placeholders. | Ask your account team. |
| The Compliance page has no AI Act card. | The policy is not enabled for your organisation. | Ask your account team whether it applies to you. |
| The re-acceptance prompt appears after sign-in. | A new edition of an accepted document was published. | Read the documents, ask your counsel if needed, then accept. |

## Related

- [Security and trust evidence](https://noxtica.com/docs/security/): what Noxtica publishes about security and assurance.
- [Legal basis register and receipts](https://noxtica.com/docs/compliance/legal-basis/): record the sub-processor acceptance.
- [Privacy and compliance controls in Backoffice](https://noxtica.com/docs/compliance/overview/): map of every privacy page.
- [Uptime checks and status](https://noxtica.com/docs/observability/uptime-alerts-status/): the status page and incident feed.
- [DPA](https://noxtica.com/dpa/), [Subprocessors](https://noxtica.com/subprocessors/) and [Privacy Policy](https://noxtica.com/privacy/): the public legal documents.

---

Source: https://noxtica.com/docs/concepts/agentic-security/
Markdown: https://noxtica.com/docs/concepts/agentic-security/index.md
Last updated: 2026-09-11

# Agentic Security

**Definition.** At Noxtica, "agentic" covers three distinct workflows: an operator can investigate tenant information with the [AI Assistant](https://noxtica.com/docs/concepts/ai-assistant/), an external agent can read permitted tenant information through [MCP](https://noxtica.com/docs/concepts/mcp-integration/), and a tenant can govern supported incoming agent identities with [Know Your Agent](https://noxtica.com/docs/concepts/know-your-agent/).

The problem is not a lack of automation. It is unclear authority. Security teams need to know whether an automated system is assisting an operator, reading a data source, or arriving as traffic—and which person or policy remains accountable in each case.

One boundary applies to all three meanings: Noxtica does not give an assistant or MCP client autonomous write access to customer systems. Read surfaces provide context for a human or customer-owned workflow. Traffic actions occur only through policy your team configures or code your team controls.

## When it applies

Use this model when:

- operators need a faster way to summarize policies, domains, recent activity, or risk;
- an internal AI workflow needs structured, read-only access to the same tenant-scoped context;
- product or security teams need differentiated treatment for supported automated-agent identities; or
- reviewers need to show who requested information and which policy caused a traffic action.

These are separate capabilities with separate eligibility. Adopting one does not activate the others.

## The three meanings

### 1. We operate agentically

Where the AI Assistant is available, a signed-in operator asks questions inside the console. The assistant can retrieve the same supported read-only surfaces the operator is permitted to view, such as policies, rules, domains, recent fingerprints, risk distribution, and audit information.

The output is a conversational summary for investigation. An operator uses it to choose which record, trend, or policy to inspect next. It does not change configuration or act on traffic. See [AI Assistant](https://noxtica.com/docs/concepts/ai-assistant/).

### 2. You integrate agentically

For tenants with MCP enabled, an operator issues a scoped credential and configures an MCP-compatible client with the provisioned connection details. The client can request allowed policies, rules, alerts, and risk distribution over the read-only MCP surface.

The output is structured tenant context that your agent can summarize or pass into a customer-owned review workflow. MCP does not expose write tools, and data from one tenant is not a cross-tenant intelligence feed. See [MCP Integration](https://noxtica.com/docs/concepts/mcp-integration/).

### 3. We police the agentic web

Where KYA is provisioned, a tenant records which supported agent identities it recognizes and how known, unknown, or denied agents should be treated. Noxtica evaluates the identity evidence presented with traffic; your application or configured enforcement policy decides whether to allow, observe, challenge, or block.

The output is identity and policy context, not a grant of authority and not proof that an agent's requested operation is safe. Apply normal authorization and business rules after the traffic decision. See [Know Your Agent](https://noxtica.com/docs/concepts/know-your-agent/) and [Browser Security](https://noxtica.com/docs/concepts/browser-security/).

## How the pieces compose

| Meaning                   | Customer entry point                                               | Output                                           | Decision owner                               |
| ------------------------- | ------------------------------------------------------------------ | ------------------------------------------------ | -------------------------------------------- |
| We operate agentically    | AI Assistant in an eligible operator console                       | Human-readable summary of permitted tenant state | Signed-in operator                           |
| You integrate agentically | Opt-in MCP connection with a scoped token                          | Structured, read-only tenant context             | Your agent workflow and its human owner      |
| We police the agentic web | KYA registry plus application or managed policy, where provisioned | Presented identity status and policy context     | Your application or configured tenant policy |

The assistant and MCP can help investigate why traffic was assessed a certain way. KYA can add agent identity context. Device risk, confidence, flags, route sensitivity, and your policy still determine the response. This separation keeps explanation, authorization, and enforcement reviewable.

## Outputs and decisions

Common customer outcomes include:

- reducing time spent locating the policy or traffic segment relevant to an investigation;
- feeding approved Noxtica context into an internal reporting or triage workflow;
- distinguishing a supported, verified automated-agent claim from an unknown or denied claim; and
- retaining a review path from risk evidence to the customer-owned action.

None of these outputs proves human identity, business intent, or permission to perform an application operation. Treat them as inputs to your existing access-control, fraud, and incident-response processes.

## Eligibility and limits

- The assistant remains read-only. Availability, quotas, and supported read surfaces depend on the provisioned plan and operator permissions.
- MCP is read-only, off by default, and tenant-scoped. Enablement and connection details are provided for eligible tenants.
- KYA and managed risk-action controls are not implied for every tenant or every agent identity scheme. Confirm supported deployment and provisioning before launch.
- Agents that do not present supported verifiable identity remain unknown; your policy must define the fallback.
- Native mobile attestation is a separate capability and is not included by the browser or agent concepts.

## Where we're headed

Today, humans set policies and thresholds. Self-calibration and feedback-driven tuning are being explored for future releases, but they are not part of the current contract. Any future write capability would require a separately documented permission and approval model; the assistant and MCP described here remain read-only.

## Read deeper

- [AI Assistant](https://noxtica.com/docs/concepts/ai-assistant/) — console investigation, current read-only scope, and eligibility.
- [MCP Integration](https://noxtica.com/docs/concepts/mcp-integration/) — tenant-scoped external read access.
- [Know Your Agent](https://noxtica.com/docs/concepts/know-your-agent/) — defensive agent identity and policy.
- [Browser Security](https://noxtica.com/docs/concepts/browser-security/) — customer-owned decisions and managed controls.
- [Calibration](https://noxtica.com/docs/concepts/calibration/) — how to read score, confidence, and reasons together.
- [Features: AI-assisted operations](https://noxtica.com/docs/features/#ai-assisted-operations) — the assistant and MCP customer surfaces.
- [Features: agent identity and control](https://noxtica.com/docs/features/#agent-identity-and-control) — eligible incoming-agent governance.
- [Backend integration](https://noxtica.com/docs/backend-integration/) — using risk outputs in your own application policy.

---

Source: https://noxtica.com/docs/concepts/ai-assistant/
Markdown: https://noxtica.com/docs/concepts/ai-assistant/index.md
Last updated: 2026-10-27

# AI Assistant

**Definition.** The AI Assistant is a console-based **operator copilot**. It helps a signed-in operator find and summarize supported Noxtica information without turning the assistant into an autonomous administrator.

The problem it solves is investigation overhead. Policies, domains, recent assessments, risk distribution, and audit records can answer an operational question, but finding the relevant slice takes time. The assistant provides a conversational starting point; the underlying product records remain the source an operator reviews.

## When it applies

Use the assistant for questions such as:

- Which policies and rules are relevant to this domain?
- What does recent risk activity look like?
- Which recent fingerprints or audit records should I inspect?
- What context should I collect before a policy review?

Do not use an assistant response as the sole basis for blocking traffic, approving a transaction, attributing intent, or closing an investigation. Verify material conclusions against the linked console records and your normal operating procedure.

## How customers use it

1. Sign in to the operator console with an account that has the Admin role. Lower roles do not see the assistant button.
2. Open the assistant if it is enabled for your tenant.
3. Ask a bounded question about the tenant and time period you are investigating.
4. Review the returned summary and follow up in the relevant policy, domain, fingerprint, risk, or audit view.
5. Make any operational decision through the normal product control or your own application workflow.

The useful output is a concise summary and a narrower investigation path. It does not create a new source of truth, expand the operator's permissions, or perform a traffic action.

## How Noxtica does it

The public contract is defined by the controls around the assistant, not by a particular model:

- **Operator-session scope.** The assistant runs in the context of the signed-in operator.
- **Permission checks.** Supported tool calls are checked against the operator's current role-based access.
- **Tenant boundary.** Reads are limited to the active tenant and supported product surfaces.
- **Usage allowance.** Assistant availability and usage limits follow the tenant's provisioned plan.
- **Auditability.** Assistant tool activity is recorded so operators can review how tenant information was accessed.

Supported deployments can offer more than one model provider. The available provider set depends on the tenant's plan and configuration; a provider name is not a guarantee about response quality. Review assistant output before it informs a customer-impacting decision.

### Phase 1 — read-only tools

The current assistant tool boundary is **read-only**. Subject to operator permissions and tenant availability, it can retrieve and summarize:

- policies and rules;
- domains;
- recent fingerprints;
- risk distribution; and
- audit information.

It cannot change configuration, create or delete records, flip feature settings, or challenge, block, or otherwise act on traffic.

### Phase 2 — write behind a flag

This heading is retained to make the boundary explicit: write tools are not part of the current assistant contract. Prior roadmap references do not make mutation available or commit a delivery date. Plan integrations against read-only behavior unless a future product document expressly replaces this boundary for your tenant.

## Outputs and decisions

| Assistant output         | Useful next decision                                                     |
| ------------------------ | ------------------------------------------------------------------------ |
| Policy or domain summary | Decide which configuration screen an operator should review              |
| Recent-risk summary      | Choose a time range, risk tier, or segment for deeper investigation      |
| Fingerprint summary      | Open the source assessment and evaluate its score, confidence, and flags |
| Audit summary            | Identify the actor, time, or operation that needs normal audit review    |

Assistant prose can omit context or require clarification. Treat it as navigation and synthesis, not evidence that a person is fraudulent or that a policy is correct.

## Eligibility and limitations

- The assistant is available only where included and provisioned for the tenant.
- The assistant needs the Admin role. Reads remain subject to the signed-in operator's role and the active tenant.
- Usage allowances and available read surfaces may differ by plan.
- The assistant does not browse customer systems, execute customer code, or mutate Noxtica through its current tools.
- Questions that require unsupported data, another tenant's data, or a write action remain outside scope.

## Where it fits

The assistant is the "we operate agentically" part of the [Agentic Security](https://noxtica.com/docs/concepts/agentic-security/) model. It is distinct from [MCP](https://noxtica.com/docs/concepts/mcp-integration/), which lets an eligible external agent read approved Noxtica context, and [Know Your Agent](https://noxtica.com/docs/concepts/know-your-agent/), which evaluates supported identities of agents reaching your site.

## Who it fits

The assistant fits operators who work in the console and have it enabled for their tenant. It helps them choose where to look next. The questions it suits are listed under [When it applies](https://noxtica.com/docs/concepts/ai-assistant/#when-it-applies). What each summary points to is in [Outputs and decisions](https://noxtica.com/docs/concepts/ai-assistant/#outputs-and-decisions).

## How teams connect

You write no code to use the assistant. It runs in the console. The steps are under [How customers use it](https://noxtica.com/docs/concepts/ai-assistant/#how-customers-use-it). Model routing and provider keys for the assistant are set in Backoffice; see [AI assistant, MCP tokens and coding-agent keys](https://noxtica.com/docs/backoffice/ai-assistant-and-mcp/). To let your own AI client read tenant data, see [MCP Integration](https://noxtica.com/docs/concepts/mcp-integration/).

## Limits

The assistant is a helper for operators, not an authority.

- **Controlled availability.** Access is agreed with Noxtica.
- Assistant text can be wrong. It is not a verdict.
- Risk scores and levels it summarizes are probabilistic and can be wrong. Your team decides what to do with them. See [Calibration](https://noxtica.com/docs/concepts/calibration/).

What the assistant cannot reach or change, and where it is available, is listed under [Eligibility and limitations](https://noxtica.com/docs/concepts/ai-assistant/#eligibility-and-limitations).

## Common questions

### Can the assistant change my policies?

No. Its tools are read-only. [How Noxtica does it](https://noxtica.com/docs/concepts/ai-assistant/#how-noxtica-does-it) lists what it can read and what it cannot do.

### Can it see more than I can?

No. The permission checks and the tenant boundary under [How Noxtica does it](https://noxtica.com/docs/concepts/ai-assistant/#how-noxtica-does-it) apply to every read.

### How is it different from MCP access?

Each has its own audience. The assistant serves a signed-in operator in the console. MCP serves an approved external client that holds a token. They are provisioned separately. See [Where it fits](https://noxtica.com/docs/concepts/ai-assistant/#where-it-fits).

## Read deeper

- [Agentic Security](https://noxtica.com/docs/concepts/agentic-security/) — the three agent workflows and their decision owners.
- [MCP Integration](https://noxtica.com/docs/concepts/mcp-integration/) — the read-only external-agent counterpart.
- [Features: AI-assisted operations](https://noxtica.com/docs/features/#ai-assisted-operations) — the source product views and read boundaries behind an investigation.
- [Calibration](https://noxtica.com/docs/concepts/calibration/) — how to interpret risk outputs before acting.
- [Contact](https://noxtica.com/contact/) — confirm tenant eligibility and provisioning.

---

Source: https://noxtica.com/docs/concepts/browser-intelligence/
Markdown: https://noxtica.com/docs/concepts/browser-intelligence/index.md
Last updated: 2026-09-11

# Browser Intelligence

**Definition.** Browser Intelligence is the **collection and assessment layer**. It turns characteristics available during a browser session, together with supported edge context, into a site-scoped result. It is the intelligence half of the browser workflow; [Browser Security](https://noxtica.com/docs/concepts/browser-security/) describes how a customer can act on that result.

The problem it solves is ambiguity at high-volume digital entry points. A user-agent string or IP address alone cannot explain whether a session is consistent, automated, unusual, or simply privacy-conscious. Browser Intelligence combines multiple categories of evidence and returns a result your team can review.

## When it applies

Use Browser Intelligence where a browser session affects fraud or abuse exposure, including signup, login, account recovery, promotion use, checkout, content access, and other customer-defined routes. Start in observe-only application logic where the cost of customer friction is high.

This concept covers browser traffic. Native mobile attestation has separate integration and eligibility requirements and is not implied by installing the browser collector.

## How customers use it

1. Request access and obtain the Site Key for the intended environment.
2. Add the collector using [Automatic Collection](https://noxtica.com/docs/getting-started/#automatic-collection-recommended), or call `checkOnce()` when your application needs explicit timing.
3. Listen for the collection result or read the returned object.
4. Store the `fingerprintId` with the relevant session or account only when your design requires continuity.
5. Use the [Server API](https://noxtica.com/docs/api/reference/device/) or operator console to review current device and risk context.
6. Apply route-specific policy in your code, or use separately provisioned controls where available.

The SDK also reports cache state and errors so the application can distinguish a fresh assessment, a reused result, and an unavailable assessment.

## How Noxtica does it

Collection runs in the browser runtime and considers several public categories of evidence:

- **Rendering context** — consistency in browser-exposed canvas, WebGL, audio, and related media behavior.
- **Environment context** — browser-exposed fonts, platform details, and available device characteristics.
- **Consistency context** — whether the browser's claimed properties agree with its observed behavior.
- **Network context** — supported attributes such as country, network type, and datacenter classification derived during service processing.

No single characteristic decides the outcome. The product returns a combined assessment. The protected runtime is intended to make manipulation and replay harder, but it is not a guarantee that client-side code cannot be inspected or attacked.

The browser assessment does not ask for a person's name or email as an input. A device identifier is still operational data that customers should handle under their own retention, access, consent, and legal-basis requirements.

## Outputs and decisions

| Output                      | What it tells you                                            | Useful decision                                                 |
| --------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------- |
| `fingerprintId`             | A site-scoped handle for the assessed browser/device context | Link permitted observations across your own workflow            |
| `score` and `risk_level`    | The assessed level of risk                                   | Choose allow, observe, review, or step-up policy for the route  |
| `confidence`                | How much weight to place on the assessment                   | Defer a strong action when evidence is limited                  |
| `flags` and summary details | Which categories contributed to the result                   | Explain or investigate why the score changed                    |
| cache and error state       | Whether the result was reused or could not be refreshed      | Use a documented fallback instead of treating absence as safety |

## Supported limitations

- Browser settings, privacy protections, blocked scripts, content-security policy, network failure, or unsupported capabilities can reduce available evidence.
- A fingerprint identifies an assessed browser/device context, not a legal person, account owner, or guaranteed physical device.
- Cached results trade reassessment frequency for lower client work; choose the collection interval for your risk window.
- Collection modes and available fields follow the current SDK and tenant configuration.
- Client-side output should not replace server-side authentication, authorization, or transaction controls.

## Where it fits

Browser Intelligence feeds [Know Your Device](https://noxtica.com/docs/concepts/know-your-device/), which explains identifier and risk outputs. It pairs with [Browser Security](https://noxtica.com/docs/concepts/browser-security/), which covers customer-owned actions. Together they let teams observe first, choose thresholds, and introduce friction only where policy requires it.

## Read deeper

- [Getting started](https://noxtica.com/docs/getting-started/#automatic-collection-recommended) — install the current browser scripts.
- [Browser runtime](https://noxtica.com/docs/browser-runtime/) — collection, cache behavior, events, and errors.
- [Backend integration](https://noxtica.com/docs/backend-integration/) — store the identifier and retrieve device risk.
- [Features: device and browser intelligence](https://noxtica.com/docs/features/#device-and-browser-intelligence) — the customer outcome supported by combined evidence.
- [Detection signals](https://noxtica.com/docs/detection-signals/) — the public evidence categories.
- [Know Your Device](https://noxtica.com/docs/concepts/know-your-device/) — how to use the returned identifier and risk fields.
- [Browser Security](https://noxtica.com/docs/concepts/browser-security/) — how policy can act on the assessment.

---

Source: https://noxtica.com/docs/concepts/browser-security/
Markdown: https://noxtica.com/docs/concepts/browser-security/index.md
Last updated: 2026-09-11

# Browser Security

**Definition.** Browser Security is the **decision and enforcement layer**. [Browser Intelligence](https://noxtica.com/docs/concepts/browser-intelligence/) supplies an assessment; your application or a separately provisioned policy surface decides what that assessment means for a particular route.

The problem it solves is inconsistent response. Without an explicit policy, teams either ignore useful risk evidence or apply one blunt threshold everywhere. Browser Security keeps the risk input separate from the business action so a public page, signup, account recovery, and payment flow can use different responses.

## When it applies

Use Browser Security after you can observe representative traffic and explain the fields your policy consumes. It is most useful on routes where automation, account abuse, or transaction risk has a defined response and owner.

For a first rollout:

1. collect the browser result;
2. record score, risk level, confidence, flags, route, and customer outcome;
3. review the distribution by surface;
4. define the least disruptive useful action for each band; and
5. enable enforcement only after owners agree on fallback and review procedures.

## How customers use it

A tenant can implement customer-owned policy in backend code using the documented risk output. Eligible tenants may also have managed risk-action controls in the product.

Common actions are:

- **Allow** — continue the normal path.
- **Observe** — retain the assessment for analysis without adding friction.
- **Challenge or step up** — ask the application to perform additional verification. Your application owns the actual second factor or challenge.
- **Block** — deny the requested operation and retain enough context for review.
- **Tarpit** — where provisioned, slow a class of abusive traffic under an explicit policy.

Choose an action from the combination of route sensitivity, risk level, confidence, flags, and your own account or transaction context. Do not block solely because one browser characteristic is unusual.

## How Noxtica does it

The product represents enforcement as policy-driven directives or customer-consumed API fields rather than an autonomous security decision. Two rollout controls are especially important:

- **Per-domain or per-surface policy** — apply a posture to the context it was designed for instead of assuming one global threshold.
- **Shadow mode** — where available, record what a policy would have done without applying the traffic action.

Shadow output supports threshold review, expected-impact analysis, and investigation playbooks. It does not prove that future traffic will have the same distribution, so teams should continue monitoring after activation.

### The risk-action engine

Where the risk-action engine is enabled, operators configure policies that can consider:

- **Device risk** from [Know Your Device](https://noxtica.com/docs/concepts/know-your-device/).
- **Supported agent identity or policy context** from [Know Your Agent](https://noxtica.com/docs/concepts/know-your-agent/), where provisioned.
- **URL or route patterns** that define the protected surface.
- **Network or IP reputation context** available to the tenant.

The engine's useful outputs are the matched policy, intended or applied action, and associated risk context visible through the supported product views. Those records help operators answer: _Which policy matched? What evidence was available? Was the action observed or enforced?_

## How outputs inform decisions

| Observed condition                                         | Typical customer-owned response                               |
| ---------------------------------------------------------- | ------------------------------------------------------------- |
| Low risk with expected context                             | Allow and retain normal telemetry                             |
| Elevated risk with limited confidence                      | Observe or use a reversible step-up                           |
| High risk with corroborating flags on a sensitive route    | Stronger verification or manual review                        |
| Repeated critical-risk automation under an approved policy | Block or another provisioned mitigation                       |
| Collection error or missing assessment                     | Use the application's documented fallback; do not assume safe |

These are decision patterns, not universal defaults. The right consequence depends on customer journey, loss exposure, contractual requirements, accessibility, and support capacity.

## Eligibility and limitations

- Managed enforcement, shadow mode, tarpit, and KYA inputs can require tenant-specific provisioning. Confirm them before making them a launch dependency.
- A challenge directive does not supply your application's MFA, identity verification, or authorization logic.
- Browser controls do not replace server-side validation or protect non-browser protocols unless separately integrated.
- A risk output is not proof of identity, intent, fraud, or policy compliance.
- Always define behavior for timeouts, missing results, stale cached results, and unavailable optional signals.

## Where it fits

Browser Security is the Security pillar. It consumes the outputs described by [Calibration](https://noxtica.com/docs/concepts/calibration/) and can combine device risk with separately eligible agent context. In the agentic-security model, the policy remains customer-owned even when the product carries out a configured action.

## Read deeper

- [Browser Intelligence](https://noxtica.com/docs/concepts/browser-intelligence/) — the assessment layer this policy consumes.
- [Agentic Security](https://noxtica.com/docs/concepts/agentic-security/) — the boundaries between assistant, MCP, KYA, and enforcement.
- [Backend integration](https://noxtica.com/docs/backend-integration/#customer-policy) — implement customer-owned server policy.
- [Integration flow: decision](https://noxtica.com/docs/integration-flow/#4-customer-policy) — follow the assessment into application logic.
- [Features: bot, abuse, and network defense](https://noxtica.com/docs/features/#bot-abuse-and-network-defense) — the customer-facing defense and policy surfaces.
- [Engineering principles](https://noxtica.com/docs/principles/#03-false-positives-are-not-acceptable-losses) — why rollout starts with observation.

---

Source: https://noxtica.com/docs/concepts/calibration/
Markdown: https://noxtica.com/docs/concepts/calibration/index.md
Last updated: 2026-09-11

# Calibration

**Definition.** Calibration is the practice of treating a Noxtica result as a **risk read, not a binary verdict**. The result includes a score, a risk level, a confidence value, and flags or reasons. Your team decides what combination justifies observation, review, step-up, or denial on each surface.

The problem it solves is false certainty. A single "bot" label hides uncertainty and makes it hard to explain customer friction. A multi-field result lets a reviewer see both the assessed risk and how much evidence supported it.

Calibration here describes how the current product exposes and applies risk information. It is not a guarantee that a particular score has the same business meaning for every tenant, route, geography, or time period.

## When it applies

Use calibration whenever the cost of being wrong differs by workflow:

- signups where automated account creation is costly but conversion matters;
- login or recovery where a false positive can lock out a customer;
- checkout where device evidence is one input alongside transaction context;
- public content where observation may be preferable to friction; and
- policy reviews where operators need to explain why a threshold exists.

## How Noxtica does it

- **Score and tier.** The numeric score and named risk level provide an ordered risk signal that application code and operators can consume.
- **Confidence.** Confidence indicates how much weight to place on the assessment; it is a separate dimension from severity.
- **Flags or reasons.** Named contributing conditions provide an investigation trail rather than an unexplained label.
- **Operator-owned thresholds.** Your code and enabled policy controls determine what happens at each threshold.

This is a public output contract, not a disclosure of internal weighting or detection mechanics. For the current response shape, see [Backend integration: Keep result states separate](https://noxtica.com/docs/backend-integration/#keep-result-states-separate) and the [Device API reference](https://noxtica.com/docs/api/reference/device/).

## Using the outputs

| Read             | Question it answers                               | Decision use                                                        |
| ---------------- | ------------------------------------------------- | ------------------------------------------------------------------- |
| Score            | Where does this assessment sit on the risk scale? | Sort, segment, or apply a customer-defined threshold                |
| Risk level       | Which named operating band contains the score?    | Map the assessment to a route-specific policy                       |
| Confidence       | How much evidence supported the assessment?       | Prefer observation or reversible step-up when confidence is limited |
| Flags or reasons | What contributed to the result?                   | Investigate, explain, or tune the customer-owned response           |

Review these fields together. A higher-risk result with limited confidence may call for more evidence rather than a hard block. A repeated pattern with corroborating flags may justify stronger treatment on a sensitive route.

## Operating a calibrated policy

1. Start with observation on representative traffic.
2. Separate results by surface and customer outcome; do not assume one threshold fits every route.
3. Review score, risk level, confidence, and flags together.
4. Choose the least disruptive action that addresses the measured risk.
5. Record false-positive and false-negative outcomes in your own review process.
6. Revisit thresholds after traffic, product, or attacker behavior changes.

The console and API provide inputs for this process. Your team owns the labels, outcome data, escalation path, and final policy.

## Supported limitations

- A score does not prove that a session is automated, fraudulent, or operated by a particular person.
- Confidence is not identity assurance and should not replace authentication or authorization.
- Missing or blocked browser capabilities can reduce available evidence.
- Scores should be evaluated against your own traffic and outcomes before enforcement.
- Changes in traffic mix can make an old threshold less useful even when the response schema is unchanged.

## Where we're headed

This section is **forward-looking** and not part of the current product contract.

> **Today, operators tune policies and thresholds. Self-calibration and feedback-driven threshold changes are being explored for future releases.**

The current workflow does not autonomously learn from customer outcomes or change policy. If your organization maintains labels or review outcomes, use them to evaluate the thresholds you control rather than assuming Noxtica will tune itself.

## Where it fits

Calibration sits beneath [Know Your Device](https://noxtica.com/docs/concepts/know-your-device/) and [Browser Intelligence](https://noxtica.com/docs/concepts/browser-intelligence/), which produce the read, and [Browser Security](https://noxtica.com/docs/concepts/browser-security/), which turns a customer-owned policy into an action.

## Read deeper

- [Why calibration, not verdicts](https://noxtica.com/docs/why-calibration/) — the full decision philosophy.
- [Features: risk and decisioning](https://noxtica.com/docs/features/#risk-and-decisioning) — where the output appears.
- [Engineering principles](https://noxtica.com/docs/principles/#01-calibration-over-verdicts) — calibration as an operating constraint.
- [Detection signals: how a signal becomes a decision](https://noxtica.com/docs/detection-signals/#how-a-signal-becomes-a-decision) — the public assessment flow.
- [Backend integration](https://noxtica.com/docs/backend-integration/#read-the-device-on-your-server) — consume the result in server-side logic.

---

Source: https://noxtica.com/docs/concepts/
Markdown: https://noxtica.com/docs/concepts/index.md
Last updated: 2026-09-11

# Concepts & Glossary

Use this section to connect Noxtica terminology to an operating decision. Each concept explains the problem it addresses, where it appears in the product or API, the output your team receives, and the boundary of what that output can establish.

Noxtica separates **intelligence** from **action**. The intelligence layer describes a browser, device, network context, or verified agent claim. Your application and configured policies decide whether to allow, observe, step up, or block. The AI Assistant and MCP integration are read-only ways to investigate that tenant-scoped information; neither is an autonomous control plane.

## The Intelligence pillar

Use the intelligence concepts when you need evidence about traffic before changing the customer journey.

- **[Know Your Device (KYD)](https://noxtica.com/docs/concepts/know-your-device/)** — turns a browser assessment into a site-scoped identifier, risk score, risk level, confidence, and flags that your application can store and review.
- **[Know Your Agent (KYA)](https://noxtica.com/docs/concepts/know-your-agent/)** — where provisioned, compares cryptographically presented agent identity with the trust policy for your tenant. It does not grant an agent authority.
- **[Browser Intelligence](https://noxtica.com/docs/concepts/browser-intelligence/)** — explains the categories of browser and edge context that contribute to an assessment, and how to consume the result through the SDK, console, or Server API.

These outputs support fraud review, account protection, signup controls, abuse investigation, and traffic analysis. They are risk evidence, not proof of a person's identity or intent.

## The Security pillar

Use the security concept after your team has decided what each level of risk should mean for a particular route or transaction.

- **[Browser Security](https://noxtica.com/docs/concepts/browser-security/)** — applies customer-owned policy to intelligence outputs. Your application can act on API results directly; eligible tenants may also use configured risk-action controls and shadow mode.

Keep collection and enforcement separate during rollout. Observe the output on representative traffic, choose thresholds for each surface, and only then introduce customer friction.

## The Agentic spine

"Agentic" describes three different customer workflows. It does not mean that Noxtica autonomously changes your systems.

- **[Agentic Security](https://noxtica.com/docs/concepts/agentic-security/)** — the umbrella for investigating with the assistant, connecting read-only external agents through MCP, and governing incoming automated agents.
- **[MCP Integration](https://noxtica.com/docs/concepts/mcp-integration/)** — an opt-in, tenant-scoped, read-only MCP surface for eligible tenants. External agents can retrieve allowed Noxtica context but cannot modify it.
- **[AI Assistant](https://noxtica.com/docs/concepts/ai-assistant/)** — a console-based operator assistant that reads only what the signed-in operator is permitted to read and returns summaries for human review.
- **[Know Your Agent (KYA)](https://noxtica.com/docs/concepts/know-your-agent/)** — a separate defensive capability for evaluating agents that reach your application; availability and supported identity paths depend on provisioning.

## Calibration

- **[Calibration](https://noxtica.com/docs/concepts/calibration/)** — explains how to use the score, risk level, confidence, and flags together instead of treating any one field as a binary verdict.

Calibration matters when the cost of a false positive differs by workflow. A medium-risk signup, a high-value payment, and a public read-only route can use the same assessment differently because your policy owns the consequence.

## Start with your task

| If you need to…                                   | Start here                                                   | Continue with                                                              |
| ------------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------- |
| Add browser assessment to a site                  | [Browser Intelligence](https://noxtica.com/docs/concepts/browser-intelligence/) | [Getting started](https://noxtica.com/docs/getting-started/#automatic-collection-recommended) |
| Use an identifier or risk result in backend logic | [Know Your Device](https://noxtica.com/docs/concepts/know-your-device/)         | [Backend integration](https://noxtica.com/docs/backend-integration/)                          |
| Choose risk thresholds and customer treatment     | [Calibration](https://noxtica.com/docs/concepts/calibration/)                   | [Features: risk and decisioning](https://noxtica.com/docs/features/#risk-and-decisioning)     |
| Observe, challenge, or block by policy            | [Browser Security](https://noxtica.com/docs/concepts/browser-security/)         | [Integration flow: decision](https://noxtica.com/docs/integration-flow/#4-customer-policy)          |
| Investigate tenant state in the console           | [AI Assistant](https://noxtica.com/docs/concepts/ai-assistant/)                 | [Features: AI-assisted operations](https://noxtica.com/docs/features/#ai-assisted-operations) |
| Let an external agent read approved context       | [MCP Integration](https://noxtica.com/docs/concepts/mcp-integration/)           | [Features: AI-assisted operations](https://noxtica.com/docs/features/#ai-assisted-operations) |
| Evaluate incoming automated agents                | [Know Your Agent](https://noxtica.com/docs/concepts/know-your-agent/)           | [Agentic Security](https://noxtica.com/docs/concepts/agentic-security/)                       |

## Availability and scope

Browser collection, its returned fields, and server-side device lookup are documented in the public integration guides. Assistant access, MCP, KYA, managed enforcement, and native mobile capabilities can depend on plan, tenant provisioning, and supported deployment context. Confirm those capabilities for your tenant before making them a launch dependency. The browser concepts do not imply that native mobile attestation is included.

## Related reading

- [Features reference](https://noxtica.com/docs/features/) — customer-visible capabilities and where they appear.
- [Getting started](https://noxtica.com/docs/getting-started/) — install the browser collector and receive a result.
- [Backend integration](https://noxtica.com/docs/backend-integration/) — look up device risk and use it in server-side policy.
- [Engineering principles](https://noxtica.com/docs/principles/) — the operating constraints behind every surface.
- [Why calibration, not verdicts](https://noxtica.com/docs/why-calibration/) — the decision model behind the platform.
- [Detection signals](https://noxtica.com/docs/detection-signals/) — the evidence categories behind browser assessment.
- [Integration flow](https://noxtica.com/docs/integration-flow/) — browser collection to customer-owned decision, end to end.

---

Source: https://noxtica.com/docs/principles/
Markdown: https://noxtica.com/docs/principles/index.md
Last updated: 2026-09-11

# Engineering Principles

These principles are customer-operating constraints, not promises that every deployment has the same configuration or outcome. Use them to review an integration before it acts on real traffic and whenever you change a policy, data source, or customer journey.

## 01. Calibration over verdicts

Your team owns the action; Noxtica provides a calibrated assessment and the context available for it.

A browser result can include a numeric score, five-level risk tier, confidence, and named flags or reason categories. Agent, network, attestation, behavioral, or identity modules can add their own status where enabled. None of those fields should be reduced to “person is a bot” or “person is safe.”

**Where you'll see this**

- Browser callbacks and server lookups expose risk separately from confidence.
- Fingerprint detail and analytics show reason categories and population context, subject to role and retention.
- Risk-action policies let you choose allow, observe, challenge, review, or block by journey.
- Shadow or observe-only modes, where available, show a proposed action without applying it.

**How to operate it**

1. Establish distributions and known outcomes for each domain and journey.
2. Define the cost and reversibility of each action.
3. Choose thresholds for that route rather than reusing one global cutoff.
4. Treat low confidence, missing evidence, and integration errors as their own paths.
5. Review outcomes and customer friction before tightening policy.

**The trade-off**

Calibration requires a policy and an owner. It is less convenient than a universal `if bot, block` rule, but it exposes uncertainty and lets checkout, login, content, and account-recovery flows make different choices.

## 02. Decisions you can defend

A consequential decision needs a reviewable receipt: what was assessed, which public reason families mattered, how confident the system was, which policy applied, and what action followed.

“Defensible” does not mean revealing hidden probes, scoring weights, anti-evasion methods, or proprietary detection logic. It means giving an authorized customer operator enough stable, customer-facing context to understand and review the outcome.

**Where you'll see this**

- The result contains documented risk fields and named reasons where applicable.
- Fingerprint, risk-action, investigation, and audit views connect an assessment to operator-visible context.
- Policy and configuration changes appear in the relevant customer surfaces and audit history when enabled.
- Exports, alerts, and event sinks can move eligible records into a customer's case workflow.

**How to operate it**

- Keep the assessment identifier, timestamp, domain, policy version or name, action, and appeal outcome needed for your review process.
- Map public reason categories to internal support language without exposing detection recipes.
- Require a second reviewer for high-impact policy changes where your governance calls for it.
- Test that support staff can find a record and route a customer to recovery without needing production secrets.

**The trade-off**

Stable public contracts and reviewable policy changes take more discipline than silently changing a black box. They also make regressions, disputed actions, and operational ownership easier to identify. Exact change-notice and version commitments come from your service agreement, not this principle.

## 03. False positives are not acceptable losses

A missed abusive request and an interrupted legitimate customer are both failures. Their costs differ by journey, so the correct response is to measure both rather than optimize only for detection.

**Where you'll see this**

- Five risk tiers preserve more decision room than a binary outcome.
- Confidence remains separate from risk so limited evidence does not masquerade as certainty.
- Public reason families distinguish privacy choices, shared infrastructure, unfamiliar devices, and suspicious contradictions.
- Reference policies prefer observation or reversible step-up for ambiguous cases and reserve blocking for reviewed conditions.

**How to operate it**

- Track challenge completion, abandonment, support contacts, reversals, confirmed abuse, and unknown/error rates.
- Segment results by route, browser population, device class, locale, and other appropriate cohorts.
- Maintain allow or bypass treatment for approved automation and operational monitoring.
- Provide an accessible fallback and an appeal or recovery path for consequential decisions.
- Re-evaluate policy after traffic shifts, browser releases, consent changes, or new integrations.

**The trade-off**

A conservative starting policy can allow some abuse while you gather evidence. An aggressive policy can suppress visible abuse while hiding customer loss. Noxtica does not promise a universal false-positive rate, catch rate, or “no CAPTCHA” experience; those are deployment outcomes to measure against your own labeled traffic.

## 04. Privacy by construction

Collect and retain only what has a defined customer purpose, scope it to the right tenant and domain, and keep optional or sensitive capture behind explicit controls.

Browser characteristics and a returning-device handle do not require a name or email, but they can still be personal data depending on law and use. Network context, session replay, interaction telemetry, behavioral biometrics, identity evidence, and external enrichment carry different obligations. “Hashed” or “pseudonymous” does not mean “not personal.”

**Where you'll see this**

- Site Keys are bound to registered origins and environments can be kept separate.
- Roles, tenant scope, API-key scopes, and module status constrain customer access.
- Domain and settings surfaces govern eligible collection mode, sampling, retention, redaction, consent/legal-basis admission, DNT/GPC treatment, exports, and deletion workflows.
- Behavioral biometrics, replay, raw-network retention, investigation, and other sensitive surfaces require specific activation or review.
- Audit and data-operations views help authorized operators review configuration and lifecycle activity.

**How to operate it**

1. Inventory the capability and data categories actually enabled for each domain.
2. Record purpose, legal basis or consent, recipient, retention, and deletion path.
3. Use the least-privilege role and API scope; keep secret keys on trusted servers.
4. Apply redaction and minimization before enabling replay, detailed interaction, or exports.
5. Review your current contract, privacy notice, subprocessor information, and jurisdiction-specific obligations.

**The trade-off**

Minimization can reduce continuity, investigation depth, or model confidence. Optional data can improve context but increases review and governance work. No universal hosting region, transfer restriction, deletion timeline, certification, air-gap option, or subprocessor commitment is created by this page; those boundaries must be stated in current legal documents and the customer's signed agreement.

**The specifics**

For a customer review, ask concrete configuration questions instead of relying on an absolute privacy label:

- Which domains and environments have active Site Keys?
- Which collection mode, cache interval, optional signals, and enforcement policies are active?
- Are replay, RUM, behavioral biometrics, network-detail retention, identity, or investigation modules enabled?
- What is the configured retention and deletion workflow for each data family?
- Which roles, API scopes, exports, sinks, and external providers can access or receive data?
- What happens when consent is denied, an API is unavailable, a result is missing, or confidence is low?

Do not publish signing keys, algorithms, rotation schedules, hidden probes, scoring weights, or internal feature controls as customer configuration. Use the supported install, settings, API, and contract surfaces.

## How the principles compose

These four principles reinforce each other:

- Calibration over verdicts only helps when the reasons, confidence, policy, and action are reviewable.
- Defensible decisions expose both abuse coverage and customer harm, making false-positive control measurable.
- False-positive control depends on privacy-aware interpretation: a missing signal or privacy choice is not proof of evasion.
- Privacy-aware design needs calibration because minimizing data can reduce confidence, and policy must respond safely to that uncertainty.

## Apply the principles to a rollout

| Phase       | Customer action                                                                     | Evidence to keep                                                             |
| ----------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| **Scope**   | Name the journey, owner, eligible modules, data purpose, and possible actions       | Approved configuration and measurement plan                                  |
| **Observe** | Install or enable without irreversible enforcement                                  | Baseline distributions, unknown/error rate, labeled outcomes, support impact |
| **Review**  | Inspect reason families, confidence, cohorts, and proposed actions                  | Policy rationale and reviewer decision                                       |
| **Enforce** | Promote only the reviewed routes and thresholds                                     | Action history, customer-friction and abuse metrics                          |
| **Revisit** | Reassess after meaningful traffic, integration, browser, provider, or legal changes | Updated comparison and rollback decision                                     |

## Related reading

- [Why calibration, not verdicts](https://noxtica.com/docs/why-calibration/) — turn risk and confidence into a policy.
- [Threat categories](https://noxtica.com/docs/threat-categories/) — public reason families and their interpretation limits.
- [Detection signals](https://noxtica.com/docs/detection-signals/) — what evidence availability means without exposing hidden probes.
- [Use cases](https://noxtica.com/docs/use-cases/) — reference rollout patterns.
- [Customer capability reference](https://noxtica.com/docs/features/) — configuration, output, eligibility, and limitations by family.

---

Source: https://noxtica.com/docs/concepts/know-your-agent/
Markdown: https://noxtica.com/docs/concepts/know-your-agent/index.md
Last updated: 2026-10-27

# Know Your Agent (KYA)

**Definition.** Know Your Agent is a **defensive trust-policy concept** for automated traffic. Where KYA is provisioned, a tenant can compare supported cryptographic agent identity claims with its own known, allowed, or denied entries.

The problem it solves is that an agent name or user-agent string is only a claim. Organizations need a stronger input before treating an automated client as known, while still defining safe behavior for clients that cannot present supported identity evidence.

KYA governs trust treatment at the traffic boundary. It does not grant an agent authorization inside your application, prove that an agent's requested operation is safe, or enable the agent to act.

## When it applies

Use KYA when your application receives automated traffic and needs to distinguish:

- a supported identity claim that verifies and matches tenant policy;
- a supported identity claim that verifies but is not yet known to the tenant;
- a denied identity; and
- traffic with absent, invalid, or unsupported identity evidence.

Your fallback for unknown traffic matters as much as the allow list. Observe or apply existing bot-risk policy until the identity and business purpose are understood.

## How customers use it

For an eligible deployment:

1. Inventory the automated agents that are expected to reach the protected domains.
2. Record supported identity references and the tenant's desired trust treatment.
3. Define separate behavior for known, denied, and unknown claims.
4. Observe matches and non-matches before introducing enforcement.
5. Apply the result through customer-owned application logic or provisioned [Browser Security](https://noxtica.com/docs/concepts/browser-security/) controls.
6. Review entries when an agent changes keys, signing authority, ownership, or business purpose.

The useful output is identity-verification and policy-match context associated with the request. Combine it with route sensitivity, device or browser risk, and normal application authorization.

## How Noxtica does it

KYA uses public cryptographic identity references instead of trusting a display name:

- **JWK thumbprints** — stable references derived from public-key material can identify which key presented the claim.
- **Signature-Agent hosts** — the declared signing authority provides a host identity that can be checked as part of a supported verification path.
- **Web Bot Auth verification** — where supported, signed request evidence can be verified before tenant policy is evaluated.

These are public contract inputs. No single identifier establishes the agent's intent, the human or organization behind every action, or permission to access an application resource.

## Outputs and decisions

| Output state                    | What it means                                               | Customer decision                                                       |
| ------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------- |
| Verified and allowed            | Supported identity evidence matches an allowed tenant entry | Continue to normal application authorization; allow or observe by route |
| Verified and denied             | Supported identity evidence matches a denied tenant entry   | Apply the tenant's approved deny or challenge policy                    |
| Verified but unknown            | The claim verifies but has no matching trust entry          | Observe, review ownership and purpose, then update policy deliberately  |
| Invalid, absent, or unsupported | KYA cannot establish a supported identity match             | Fall back to browser, device, network, and route policy                 |

An "allowed" result is not a bypass. The application still checks authentication, authorization, rate limits, and business rules.

Noxtica checks the signature, key reference, and validity window. Each request resolves to a plain verification state: verified, unsigned, invalid signature, expired, or replayed. The result is recorded beside the risk read and contributes to it. A verified claim adds context. An invalid signature is a risk signal. Expired and replayed signatures are detected. Unsigned traffic stays unknown, not hostile.

## What KYA is not

- It is **not** [MCP](https://noxtica.com/docs/concepts/mcp-integration/). MCP lets your external agent read approved Noxtica context; KYA evaluates agents arriving as traffic.
- It is **not** the [AI Assistant](https://noxtica.com/docs/concepts/ai-assistant/). The assistant helps an operator investigate tenant state.
- It is **not** proof of personhood, delegated business authority, or transaction approval.
- It does **not** identify every bot. Agents without a supported identity path remain unknown and require a fallback policy.

## Eligibility and limitations

- KYA availability and supported identity standards depend on tenant provisioning and deployment context.
- Do not make KYA a launch dependency until the account team confirms eligibility and the intended agent identity path.
- Key rotation, authority changes, and malformed signatures can change verification status; maintain an operational review path.
- Browser and device scoring can complement KYA but cannot turn an unsupported identity claim into a verified one.

## Where it fits

KYA is the incoming-agent part of the Intelligence pillar and the "police the agentic web" part of [Agentic Security](https://noxtica.com/docs/concepts/agentic-security/). It supplies trust context; [Browser Security](https://noxtica.com/docs/concepts/browser-security/) or customer code supplies the action.

## Who it fits

KYA helps you answer three questions about automated traffic.

- **Which agents identify themselves?** [When it applies](https://noxtica.com/docs/concepts/know-your-agent/#when-it-applies) lists the four cases KYA separates. [Outputs and decisions](https://noxtica.com/docs/concepts/know-your-agent/#outputs-and-decisions) shows the result for each.
- **Is this claim known to us?** A verified claim that your team has not reviewed yet is the "Verified but unknown" row in [Outputs and decisions](https://noxtica.com/docs/concepts/know-your-agent/#outputs-and-decisions).
- **What should unknown traffic do?** The fallback for unknown traffic is set out in [When it applies](https://noxtica.com/docs/concepts/know-your-agent/#when-it-applies).

## How teams connect

KYA has no public sample code. Setup runs through your account team and depends on tenant provisioning. Three surfaces are involved:

- **Request path.** Supported signed requests are verified where your domains receive traffic. This needs compatible signing and an edge integration.
- **Server verification.** Your backend can ask Noxtica to verify an agent request with a server-held credential. Where provisioned, it can also carry verified agent context in an agent identity envelope. See [Backend Integration](https://noxtica.com/docs/backend-integration/) and the [Server API reference](https://noxtica.com/docs/api/reference/).
- **Operator console.** Review agent identity claims and verification results in the Agentic Security view of the console. Access follows operator role and tenant scope. See [Risk actions, investigations and entity lookup](https://noxtica.com/docs/backoffice/risk-actions-and-investigations/).

## Limits

Availability: Controlled availability. [Eligibility and limitations](https://noxtica.com/docs/concepts/know-your-agent/#eligibility-and-limitations) and [What KYA is not](https://noxtica.com/docs/concepts/know-your-agent/#what-kya-is-not) state most limits in full. This section adds the rest.

- **Verify and observe today.** Enforcement is roadmap and is not part of the offer described here. Any block or challenge based on agent identity is your own logic. Nothing here commits scope or date.
- **Results are evidence.** Your team makes the decision. Read the [disclaimer](https://noxtica.com/disclaimer/).

## Common questions

### Does Know Your Agent block unwanted agents?

Not today. It verifies and observes. [Limits](https://noxtica.com/docs/concepts/know-your-agent/#limits) states that enforcement is roadmap and that any allow, challenge, or deny decision stays in your own logic.

### Is it the same as MCP or the AI Assistant?

No. [What KYA is not](https://noxtica.com/docs/concepts/know-your-agent/#what-kya-is-not) sets out the differences.

### What happens to agents that do not sign requests?

They stay unknown. [Outputs and decisions](https://noxtica.com/docs/concepts/know-your-agent/#outputs-and-decisions) shows the fallback to apply.

## Read deeper

- [Agentic Security](https://noxtica.com/docs/concepts/agentic-security/) — the three agent workflows and their boundaries.
- [Browser Security](https://noxtica.com/docs/concepts/browser-security/) — how customer policy treats allowed, denied, and unknown traffic.
- [Browser Intelligence](https://noxtica.com/docs/concepts/browser-intelligence/) — complementary browser and device evidence.
- [Threat categories](https://noxtica.com/docs/threat-categories/) — the broader automated-traffic context.
- [Features: agent identity and control](https://noxtica.com/docs/features/#agent-identity-and-control) — the customer-facing KYA capability family.
- [Contact](https://noxtica.com/contact/) — confirm KYA eligibility and provisioning.

---

Source: https://noxtica.com/docs/concepts/know-your-device/
Markdown: https://noxtica.com/docs/concepts/know-your-device/index.md
Last updated: 2026-10-27

# Know Your Device (KYD)

**Definition.** Know Your Device is Noxtica's browser-based device-intelligence concept. It turns a browser assessment into a **site-scoped fingerprint identifier** and risk context that can be used across permitted sessions and backend workflows.

The problem it solves is continuity without pretending to know a person. Account and fraud teams often need to ask whether a browser/device context has been seen before, whether its characteristics are internally consistent, and what risk evidence accompanied the assessment. KYD provides those inputs without making the final decision.

A device identifier is not a verified person, account owner, or guaranteed physical device. It is a handle for the assessed context under the current site, browser, storage, and collection conditions.

## When it applies

KYD can inform:

- new-device and returning-device review;
- signup and promotion-abuse controls;
- login, account recovery, and step-up decisions;
- transaction review alongside account and payment context; and
- support investigations into why a session received friction.

Use KYD where your team has a defined decision and fallback. Do not collect an identifier merely because it is available.

## How customers use it

1. Add the browser collector with a provisioned Site Key.
2. Call `checkOnce()` or use automatic collection to receive the current browser result.
3. Store `fingerprintId` with the relevant session or account when your retention and access design permits it.
4. Read the current risk context in the operator console or retrieve device data from the Server API with a scoped server key.
5. Combine device history and risk fields with your own account, route, and transaction context.
6. Apply the action in your backend or through separately provisioned policy controls.

See [Getting started](https://noxtica.com/docs/getting-started/#automatic-collection-recommended) for collection and [Backend integration](https://noxtica.com/docs/backend-integration/) for the supported lookup workflow.

## How Noxtica does it

[Browser Intelligence](https://noxtica.com/docs/concepts/browser-intelligence/) gathers multiple categories of browser and edge context. KYD presents the resulting customer-facing artifacts:

- **Fingerprint identifier** — a site-scoped handle returned as `fingerprintId`.
- **Device history fields** — supported first-seen, last-submitted, and last-seen timestamps available through device lookup.
- **Risk score and level** — a 0–100 score and named tier for policy segmentation.
- **Confidence** — context for how strongly to rely on the assessment.
- **Flags or reasons** — contributing conditions an operator can investigate.
- **History and comparison** — in the operator console, find a device, review its visits, and compare profiles. Where enabled for your tenant, follow related devices; relationships are leads, not proof. History follows your workspace retention and access settings. See [Fingerprints, analytics and live monitoring](https://noxtica.com/docs/backoffice/fingerprints-and-analytics/).

The protected browser runtime is designed to raise the cost of result manipulation and replay. It does not make a browser impossible to inspect, guarantee continuity, or establish a hardware or legal identity.

## Outputs and decisions

| Output                  | Customer use                                                        |
| ----------------------- | ------------------------------------------------------------------- |
| `fingerprintId`         | Associate permitted observations with a session or account workflow |
| First/last-seen context | Distinguish newly observed from previously observed context         |
| `score` and `riskLevel` | Select a route-specific review or step-up band                      |
| `confidence`            | Decide whether the available evidence supports a strong action      |
| `flags`                 | Explain and investigate what contributed to risk                    |

For example, a newly observed identifier with elevated risk and limited confidence may warrant reversible step-up rather than a permanent denial. A familiar identifier still passes normal authentication and authorization; familiarity is not approval.

## Supported limitations

- Clearing storage, private browsing, browser or device changes, privacy tools, blocked scripts, and collection settings can affect continuity or available evidence.
- A fingerprint can represent a browser profile rather than a single immutable physical device.
- Cross-site tracking is not the customer contract; use the identifier only within the provisioned tenant and site context.
- Cached assessments can be older than the current visit. Use the configured refresh interval and timestamps when freshness matters.
- Native iOS or Android attestation is separate from browser KYD and requires its own supported integration and tenant eligibility.
- Risk output complements but does not replace identity verification, authentication, authorization, or transaction controls.

## Where it fits

KYD is the device part of the Intelligence pillar. It receives evidence from [Browser Intelligence](https://noxtica.com/docs/concepts/browser-intelligence/), complements eligible [Know Your Agent](https://noxtica.com/docs/concepts/know-your-agent/) context, and supplies inputs to [Browser Security](https://noxtica.com/docs/concepts/browser-security/) or customer-owned backend policy.

## Who it fits

Device evidence suits teams that own a defined decision and a fallback. [When it applies](https://noxtica.com/docs/concepts/know-your-device/#when-it-applies) lists the decisions it can inform, and [Outputs and decisions](https://noxtica.com/docs/concepts/know-your-device/#outputs-and-decisions) explains why a familiar handle is not approval.

- **Repeated signups.** Shared devices and shared networks can limit what you can conclude when you compare device context across sessions.
- **Support and fraud review.** Use the handle as a repeatable reference when you review a session or a transaction alongside account context.

## How teams connect

These are the current public integration surfaces. Both need Evaluation access.

- **Browser script.** Follow [Getting started](https://noxtica.com/docs/getting-started/#automatic-collection-recommended) and [Browser runtime](https://noxtica.com/docs/browser-runtime/). The script runs on pages of a provisioned origin and reports a device identifier or an unavailable state to your page code.
- **Authenticated server lookup.** Follow [Backend integration](https://noxtica.com/docs/backend-integration/). Your backend sends the device identifier and reads the tenant-scoped record with a server-held credential. Keep that credential out of browser code.
- **Technical evaluation.** The [developer overview](https://noxtica.com/developers/) shows the maintained path and the current support matrix. [Contact the team](https://noxtica.com/contact/) to request Evaluation access.

[Integration flow](https://noxtica.com/docs/integration-flow/) traces the whole path from browser to policy.

## Limits

Plan for these boundaries before you rely on the output.

- **Not a person, and continuity varies.** The opening definition and [Supported limitations](https://noxtica.com/docs/concepts/know-your-device/#supported-limitations) cover what a handle represents and what breaks continuity. A missing result is not a low-risk result; treat it as unknown. Consent choices can also reduce evidence.
- **Estimates, not facts.** Scores, risk levels, and reasons are probabilistic. They are not statements of fact or certifications. Your team makes every decision. Read the [disclaimer](https://noxtica.com/disclaimer/).
- **Your responsibilities.** Optional collection follows the consent and admission settings you configure. Device handles and browser characteristics can be personal data, depending on law and use. You own the notices, consent, and legal basis for collecting them.

## Common questions

### Does a device handle identify a person?

No. It identifies an assessed browser or device context under your site. Use [identity verification](https://noxtica.com/docs/identity-verification-integration/) when you need evidence about a person.

### Does Device Intelligence block traffic?

No. It returns evidence. Your backend, or policy controls you provision separately, decides whether to allow, step up, review, or deny.

### What happens if collection fails or is blocked?

Your page receives an error or unavailable state, and no fresh evidence arrives. Treat that state as unknown, not low risk, and define a fallback.

## Read deeper

- [Getting started](https://noxtica.com/docs/getting-started/#automatic-collection-recommended) — collect the current browser result.
- [Device API reference](https://noxtica.com/docs/api/reference/device/) — retrieve device risk with a scoped server key.
- [Browser runtime](https://noxtica.com/docs/browser-runtime/) — cache, lifecycle events, errors, and collection modes.
- [Features: device and browser intelligence](https://noxtica.com/docs/features/#device-and-browser-intelligence) — interpret the identifier and its risk context.
- [Why calibration, not verdicts](https://noxtica.com/docs/why-calibration/) — choose policy without treating risk as identity.
- [Browser Intelligence](https://noxtica.com/docs/concepts/browser-intelligence/) — the evidence categories that feed KYD.

---

Source: https://noxtica.com/docs/detection-signals/
Markdown: https://noxtica.com/docs/detection-signals/index.md
Last updated: 2026-09-11

# Detection Signals

Noxtica reads several evidence layers and checks whether the available picture is coherent. It then returns customer-facing policy inputs: score, risk tier, confidence, and named reasons where applicable. Optional modules can add agent, attestation, behavioral, identity, or policy status.

Signals describe a browser, device, connection, or interaction context—not a person's identity or intent. No single layer establishes “human,” “bot,” “fraudulent,” or “safe,” and this page intentionally does not publish hidden probes, exact weights, anti-evasion methods, or proprietary implementation.

## When to use detection signals

Collect at a decision point where additional context can change a proportionate action: signup, login, checkout, account recovery, promotion redemption, content/API access, or an investigation. Do not collect every optional signal simply because it exists. Match the enabled layers, cache cadence, retention, and downstream use to a documented purpose.

Use browser callbacks when the page needs a reversible experience choice. Send the device handle to your trusted backend and use a scoped server integration when authentication, money, account access, or another consequential decision is involved.

## Four questions, one answer

Noxtica groups customer-visible interpretation into four layers. The questions below are operational shorthand, not claims that one layer can prove the answer.

| Layer           | Customer question                                             | What the output can contribute                                                                            | Common limitation                                                                                       |
| --------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Browser**     | Is this browser context internally consistent?                | Automation, browser consistency, privacy-context, and tampering reason families                           | Restricted APIs, extensions, browser updates, and collection mode can reduce evidence                   |
| **Network**     | Does the connection add risk context?                         | Coarse network type, reputation, location/provider context, or known-agent network evidence where enabled | VPNs, relays, mobile carriers, shared egress, and changing reputation are common                        |
| **Device**      | Does the environment and history support the claimed context? | Tenant-scoped recognition, device consistency, and optional integrity/attestation status                  | Storage clearing, device/browser changes, unsupported clients, and missing attestation break continuity |
| **Interaction** | Does eligible timing or journey context corroborate the rest? | Lightweight timing/journey reasons and optional behavioral evidence                                       | Short sessions, accessibility tools, UI changes, consent, and sampling can affect context               |

Contradictions between independent layers can be useful, but agreement does not prove identity or intent. Absence also has meaning: a layer can be unavailable, disabled, unsupported, denied by policy, sampled out, cached, or simply inconclusive.

## Configure the evidence you need

### Core browser collection

1. Add the exact origin in **Backoffice → Domains** and copy its Site Key.
2. Install the supported collector pattern from [Getting Started](https://noxtica.com/docs/getting-started/#automatic-collection-recommended).
3. Select the collection mode supported by the current SDK and customer journey.
4. Use `checkOnce()` for the configured cache behavior, or request a fresh assessment only when the decision justifies the extra client work.
5. Monitor `noxtica:collected`, `noxtica:cache-hit`, and `noxtica:error` as documented in [Browser Runtime](https://noxtica.com/docs/browser-runtime/).

### Optional evidence

Enable attestation, behavioral biometrics, replay/RUM, detailed network context, KYA, identity, or investigation modules only when they are entitled and their domain/tenant settings, client support, quota, purpose, consent/legal basis, redaction, and retention have been reviewed.

A feature page in Backoffice normally shows its status and configuration links when the signed-in operator has access. If the page, toggle, or output is absent, treat the capability as unavailable for that deployment until provisioning or configuration is confirmed.

### Trusted consumption

Create the narrowest required Server API key under **API Config** and keep it on the backend. Handle authentication errors, authorization errors, missing/expired records, rate limits, timeouts, and unavailable optional providers as explicit states. Never make a missing result silently equivalent to `minimal` risk.

## One calibrated risk tier

The core web assessment maps the numeric score to a five-level customer contract:

- **Minimal (`0–19`)** — little risk evidence in the available assessment.
- **Low (`20–39`)** — minor or potentially explainable anomalies.
- **Medium (`40–59`)** — mixed or incomplete suspicious evidence.
- **High (`60–79`)** — strong suspicious evidence.
- **Critical (`80–100`)** — multiple or strong reason families agree.

The tier does not arrive alone. Read it with:

- **`confidence`:** how much usable evidence supported the assessment;
- **`flags` or reasons:** the public evidence families that influenced it;
- **`fingerprintId`:** the tenant-scoped device handle returned by the browser integration;
- **cache/freshness and timestamps:** whether the decision is using a current or reused assessment; and
- **optional statuses:** agent verification, device/app integrity, identity case, or policy action where enabled.

The ranges are integration vocabulary, not universal action thresholds. Use [Why Calibration, Not Verdicts](https://noxtica.com/docs/why-calibration/) to choose route-specific policy.

## Interpret risk and confidence together

| Risk | Confidence | Interpretation                                 | Safer customer response                                        |
| ---- | ---------- | ---------------------------------------------- | -------------------------------------------------------------- |
| Low  | High       | Available evidence is consistently ordinary    | Allow under normal application controls                        |
| Low  | Low        | Little concern is visible, but little is known | Preserve ordinary controls; do not grant extra trust           |
| High | High       | Concern is strongly corroborated               | Challenge, hold, review, or apply a reviewed block rule        |
| High | Low        | Concern exists but evidence is incomplete      | Use reversible step-up or review; investigate missing evidence |

A policy can also consider the route's value, authentication state, transaction/account context, device familiarity, supported agent identity, and confirmed customer outcomes. Noxtica's output should complement—not replace—those controls.

## Sealed before it leaves the browser

Noxtica protects the assessment in transit from the browser so your supported verifier can detect invalid, expired, mismatched, or altered results. The customer contract is the outcome: trusted code validates the supported result before relying on it.

This integrity protection does not make all client data inherently trustworthy, does not prevent every replay or endpoint misuse by itself, and does not authorize the action. Keep secret credentials on your server, validate the result through the documented integration, bind it to the intended workflow where supported, enforce expiry, and retain your own authentication and authorization checks.

The exact cryptographic construction, challenge method, hidden signal probes, and internal anti-evasion controls are not customer configuration and are intentionally omitted here.

## How a signal becomes a decision

Walk through a signup attempt:

1. **Admission and collection.** The configured collector starts for the registered domain. Optional capture runs only if its policy, consent or legal-basis, sampling, and other admission conditions allow it.
2. **Assessment.** Noxtica evaluates the available browser, network, device, and eligible interaction context. Unsupported, disabled, denied, cached, or missing evidence affects what is available.
3. **Output.** The browser callback returns the documented fields. Your frontend can send the device handle with the signup request; it never sends a secret Server API key.
4. **Trusted lookup.** Your backend uses its scoped credential or supported SDK to read the eligible current record and handles errors, expiry, and `unknown` explicitly.
5. **Customer policy.** A route-specific rule combines risk, confidence, reasons, signup/account context, and any approved-agent or integrity status.
6. **Action.** The application allows, observes, requests a reversible step-up, holds for review, or blocks under the reviewed rule.
7. **Review.** Operators inspect Analytics, Fingerprints, Risk Actions, and Audit where enabled, then compare confirmed abuse with challenge completion, abandonment, support contacts, and reversals.

### Public policy example

```javascript
function decideSignup({ riskLevel, confidence, resultState }, confidenceFloor) {
	if (resultState !== 'available') return 'step_up_or_defer';
	if (confidence < confidenceFloor) return 'step_up_or_observe';
	if (riskLevel === 'critical') return 'strong_challenge_or_review';
	if (riskLevel === 'high') return 'step_up';
	if (riskLevel === 'medium') return 'observe';
	return 'allow_with_normal_controls';
}
```

The confidence floor and action mapping are intentionally yours. Determine them from representative shadow traffic and labeled outcomes rather than copying an internal or universal weight.

## Expected outputs by customer surface

| Surface                           | Use it for                                              | Typical customer-visible output                                             |
| --------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------- |
| Browser callback/API              | In-page experience and sending a handle to trusted code | Device handle, score, tier, confidence, flags/reasons, cache state          |
| Server API or SDK                 | Trusted backend policy and record lookup                | Eligible device/risk record, timestamps, reason context, explicit errors    |
| Fingerprints and Compare          | Individual review                                       | Assessment detail, evidence families, history, comparison context           |
| Analytics and Quality/Calibration | Population and policy review                            | Distribution, trends, cohorts, labels, or calibration context where enabled |
| Risk Actions                      | Enforcement rollout                                     | Applied or shadow action, policy context, and operational history           |
| Alerts, sinks, webhooks, exports  | Downstream operations                                   | Selected eligible events or records under configured scope and data policy  |

## Eligibility and limitations

Core collection requires an activated account, registered domain, Site Key, and supported browser integration. Outputs depend on collection mode, browser capabilities, cache state, network, retention, and service availability. Optional families require their own entitlement, tenant/domain activation, role, scope, quota, supported client or provider, and sometimes consent or legal-basis review.

Detection signals are probabilistic and can be incomplete, stale, or wrong. They do not prove identity, account ownership, accessibility needs, fraud, or intent. No universal detection rate, false-positive rate, latency, availability, or privacy outcome is promised here. Measure the behavior of your actual integration and apply the terms in your current contract.

## Related reading

- [Threat categories](https://noxtica.com/docs/threat-categories/) — interpretation and limits for each public reason family.
- [Browser runtime](https://noxtica.com/docs/browser-runtime/) — collection modes, caching, events, CSP, and troubleshooting.
- [Backend integration](https://noxtica.com/docs/backend-integration/) — trusted lookups, response fields, errors, and rate limits.
- [Why calibration, not verdicts](https://noxtica.com/docs/why-calibration/) — choose route-specific action from risk and confidence.
- [Customer capability reference](https://noxtica.com/docs/features/) — every customer family, surface, output, eligibility, and limitation.

---

Source: https://noxtica.com/docs/threat-categories/
Markdown: https://noxtica.com/docs/threat-categories/index.md
Last updated: 2026-09-11

# Threat Categories

Threat categories are public explanation families. They tell an authorized customer operator what kind of evidence influenced an assessment without exposing hidden probes, exact scoring weights, anti-evasion methods, or proprietary implementation.

A category is not a verdict and does not map to one fixed action. Read it with the overall risk tier, confidence, other reasons, customer journey, and your own known outcomes. The exact reasons visible to you depend on collection mode, browser support, enabled modules, tenant/domain policy, role, retention, and consent or legal-basis controls.

## 01. Automation and bots

This category covers evidence consistent with scripted browsers, automation tooling, remote control, repeated machine-driven flows, or known automated clients.

**When to use it**

Use it to protect routes where automation creates cost or abuse: signup, login, promotion redemption, inventory, checkout, content/API access, or account changes. Define expected automation—monitoring, testing, integrations, or approved agents—before enforcement.

**What the customer sees**

The result or fingerprint detail can name an automation/bot reason family, while analytics and bot-intelligence views can show aggregate volume and known-agent context where enabled. Risk Actions shows the configured action or shadow outcome.

**How to interpret it**

Automation evidence is more useful when it repeats across events or agrees with consistency, infrastructure, device, agent, or interaction context. A legitimate automated client should follow an explicit allow or agent policy rather than forcing the whole route to ignore automation evidence.

**Outcome**

Prioritize likely scripted abuse, route approved automation predictably, and apply proportionate challenge or blocking to protected operations.

**Tuning**

Start in observe-only mode where available. Segment by route, client, and known agent; review false positives and operational tools; then promote reviewed policy. Do not infer the hidden detection method from a reason name or build a permanent deny rule from a single event.

**Limitations**

Automation changes, and no detector identifies every tool. Accessibility software, test harnesses, monitoring, remote-work tools, and enterprise automation can create similar context. Signed-agent verification, when enabled, establishes a supported identity state but does not prove safe intent.

## 02. Fingerprint tampering

This category covers material inconsistency between what a browser or environment claims and what its observable behavior supports. It is intended to distinguish unexplained contradiction from an ordinary privacy choice.

**When to use it**

Use it as corroboration for spoofing, replay, evasion, or synthetic-environment investigations, especially when a valuable action also has automation, network, device, or account context.

**What the customer sees**

A public consistency/tampering reason can appear with the overall score and confidence. Authorized operators can compare the record with domain population and prior device history through eligible fingerprint or investigation views.

**How to interpret it**

One inconsistency can come from browser changes, extensions, restricted APIs, compatibility layers, or partial collection. Repeated contradictions or agreement across independent categories deserve more weight than a single unusual characteristic.

**Outcome**

Surface sessions that need step-up or review without teaching an attacker which internal test fired.

**Tuning**

Review the affected browser/OS population, fresh versus cached state, collection mode, CSP, and recent client changes. Provide allow treatment for approved tooling and avoid treating a reason label as identity proof.

**Limitations**

The category does not prove deliberate deception. Browser privacy changes and software updates can shift the population. Some evidence is unavailable on restricted or unsupported clients, which can lower confidence.

## 03. Infrastructure abuse

This category covers network context associated with higher abuse risk, such as anonymization, hosting infrastructure, reputation sources, or inconsistent location/network information. It is corroborating evidence, not guilt by network.

**When to use it**

Use it to prioritize high-cost routes, rate-limit abusive patterns, enrich an investigation, or strengthen a decision already supported by automation or account evidence.

**What the customer sees**

Eligible results and console views can expose public network/infrastructure reasons, coarse geography or provider context, and reputation status. Detailed or retained network data, external feeds, and geo/investigation views have separate controls.

**How to interpret it**

Corporate VPNs, privacy relays, mobile carriers, shared egress, cloud workspaces, journalists, and travelers can resemble risky infrastructure. Interpret the category with route, device, behavior, history, and known outcome.

**Outcome**

Identify concentrated abuse and investigate network patterns while preserving a path for legitimate users on shared or privacy-preserving infrastructure.

**Tuning**

Keep network-only reasons out of irreversible block rules. Measure by provider type and route, maintain reviewed exceptions, and monitor reputation changes. Connect a customer-selected feed only where supported and approved.

**Limitations**

Addresses and reputation change, geolocation is approximate, and shared egress is common. Raw-network retention and some feeds can require explicit opt-in, entitlement, additional disclosure, or legal review.

## 04. Privacy-browser handling

This category provides context for browsers or modes that deliberately reduce, standardize, or restrict observable detail. A privacy choice is not itself a threat.

**When to use it**

Use it to prevent low detail or standardized output from being mistaken for automation, and to compare policy friction across privacy-preserving browser populations.

**What the customer sees**

Where recognized, the assessment can identify privacy-browser context separately from tampering. Analytics and fingerprint detail can help authorized operators compare risk, confidence, challenge, and error rates for that population.

**How to interpret it**

Privacy context explains why some evidence may be limited. Continue to evaluate independent automation, network, device, agent, or interaction reasons, but do not escalate merely because the browser protects users.

**Outcome**

Keep legitimate privacy-conscious users in the normal or proportionate path while retaining protection against abusive automation using the same browser family.

**Tuning**

Review challenge completion, abandonment, support contacts, and unknown/error rates by browser family. Prefer reversible step-up when independent evidence is concerning and confidence is limited.

**Limitations**

Browser identification and behavior evolve. Noxtica does not guarantee that every privacy browser is recognized or that its users will never be challenged. Your CSP, collection mode, consent choices, and browser support affect available evidence.

## 05. Hardware checks

This category covers eligible device-integrity and environment evidence used to corroborate whether a session is consistent with its claimed execution context.

**When to use it**

Use it for high-value or high-abuse operations where browser-only evidence needs corroboration. Optional browser, GPU/CPU, mobile-app, or platform attestation should be applied only to supported clients and entitled tenants/domains.

**What the customer sees**

A customer-facing integrity or attestation status, public reason, confidence contribution, and related console record can be available. The hidden challenge, precise measurement, and validation mechanism are intentionally not exposed.

**How to interpret it**

A successful supported check is one piece of integrity evidence. An unavailable, unsupported, timed-out, or missing result is `unknown`, not automatically malicious. A failed or inconsistent result should be combined with route and other evidence before consequential action.

**Outcome**

Raise the cost of synthetic environments and add device/app integrity context to authentication, fraud, or agent policy.

**Tuning**

Enable by selected domain or application, validate client coverage in observation first, and define explicit success, failure, and unknown paths. Monitor battery/performance, browser/platform support, challenge completion, and fallback behavior in your real customer journey.

**Limitations**

Hardware and mobile attestation require supported environments and separate configuration. They do not prove a natural person's identity or benevolent intent. Availability, quotas, and provider behavior vary by account and client.

## 06. Behavioral anomalies

This category covers eligible interaction and journey context that differs from the relevant population. It is supporting evidence, not a diagnosis of whether a person is human.

**When to use it**

Use lightweight timing and journey context to corroborate other risk on selected routes. Use behavioral biometrics only after the required entitlement, explicit activation, disclosure, consent/legal-basis, minimization, and retention review.

**What the customer sees**

Depending on configuration, the result and behavioral surfaces can show a public anomaly reason, aggregate or subject-level context, journey change, and policy effect. Exact motion, keystroke, timing, or detector mechanics are not published as a customer tuning recipe.

**How to interpret it**

Interaction patterns vary across accessibility tools, motor ability, devices, cultures, network delays, task familiarity, and page design. Behavioral evidence should corroborate other categories and should not be a sole blocking reason.

**Outcome**

Identify otherwise-clean sessions or journeys that merit observation or a reversible step-up while measuring customer friction.

**Tuning**

Start with lightweight, non-biometric context where appropriate. For optional biometrics, activate only reviewed domains and monitor counterfactual or shadow results, affected cohorts, challenge completion, support impact, and reversals.

**Limitations**

Short sessions and sparse interaction reduce confidence. Journey/UI changes can shift baselines. This category must not be used to infer health, disability, or other sensitive traits, and Noxtica does not promise that it distinguishes every person from every script.

## How the categories combine

Noxtica combines the evidence available to the enabled assessment into one score, risk tier, and confidence value, with named public reasons where applicable. Some modules also return a distinct status—such as agent verification, attestation, identity-case, or policy-action state—that should retain its own meaning.

A customer policy should ask:

1. Is the result fresh enough and valid for this route?
2. Which modules and evidence were available, and how confident is the assessment?
3. Do multiple independent reason families agree?
4. Is there an ordinary explanation or approved automation path?
5. How valuable and reversible is the requested action?
6. Is an accessible challenge, review, appeal, or recovery path available?

Do not reconstruct an internal formula from category names. Use your labeled outcomes and the supported Analytics, Fingerprints, Quality/Calibration, Risk Actions, and Audit surfaces to judge policy behavior.

## Availability and configuration checklist

- The correct tenant, domain, Site Key, and environment are selected.
- Collection mode and cache interval fit the decision point.
- Optional agent, reputation, attestation, behavioral, replay, identity, or investigation modules are entitled and activated where needed.
- Operator role and API-key scopes expose only required data.
- Consent/legal basis, redaction, retention, and downstream destinations have been reviewed.
- Shadow, unknown, error, rate-limit, and provider-down behavior is defined before enforcement.

## Related reading

- [Detection signals](https://noxtica.com/docs/detection-signals/) — how browser, network, device, and interaction layers become an assessment.
- [Why calibration, not verdicts](https://noxtica.com/docs/why-calibration/) — map risk and confidence to policy.
- [Customer capability reference](https://noxtica.com/docs/features/) — customer surfaces, outputs, eligibility, and limits.
- [Browser runtime details](https://noxtica.com/docs/browser-runtime/) — collection modes, events, caching, and troubleshooting.
- [Frequently asked questions](https://noxtica.com/docs/faq/) — common integration and privacy questions.

---

Source: https://noxtica.com/docs/why-calibration/
Markdown: https://noxtica.com/docs/why-calibration/index.md
Last updated: 2026-09-11

# Why we don't tell you "this is a bot."

A binary label hides uncertainty and invites the same action everywhere. A login, a checkout, a public article, and an account-recovery change have different costs when a decision is wrong. Noxtica therefore returns calibrated policy inputs: risk, confidence, and explainable reason categories.

Calibration does not mean the system knows a visitor's identity or intent. It means the output has ordered levels that your team can compare with labeled outcomes and map to proportionate action. Noxtica provides the measurement and eligible policy surfaces; your application and operators remain responsible for the decision.

## The receipt model

> Read the risk level, confidence, and reasons together.
> Apply the policy for this customer journey.
> Keep the decision reviewable.

A useful receipt answers five customer questions:

1. **What was assessed?** The tenant, domain, device or request handle, and time.
2. **What did Noxtica return?** Score, risk tier, confidence, and public reason categories.
3. **What context was available?** Cached or fresh result, enabled modules, and any missing or unknown evidence visible through supported surfaces.
4. **Which policy applied?** The customer-owned route or workflow rule.
5. **What happened next?** Allow, observe, challenge, hold, review, or block—and any appeal or later confirmed outcome.

Use browser events for reversible in-page experience choices and a scoped server lookup or supported server SDK when a trusted backend must decide. Use **Fingerprints**, **Analytics**, **Risk Actions**, **Quality & Calibration**, and **Audit** in Backoffice where those surfaces are enabled for your role and tenant.

The receipt deliberately does not disclose hidden probes, scoring weights, anti-evasion methods, or proprietary implementation. Explainability is a stable customer outcome and reason contract, not an attacker's recipe.

## Binary verdicts hide the cost of being wrong

A binary verdict has two familiar failure modes:

- **False positive:** legitimate activity receives an unnecessary challenge, hold, review, or denial. Possible costs include abandonment, inaccessible journeys, support load, and loss of trust.
- **False negative:** abusive automation or fraud receives ordinary treatment. Possible costs include account abuse, operational load, inventory or content extraction, and financial loss.

There are also two operational failures that a binary field tends to erase:

- **Unknown:** the required result, module, or evidence is absent or unavailable.
- **Low confidence:** the assessment has too little usable evidence for the action being considered.

These states need explicit policy. Treating missing data as “safe” creates bypasses; treating it as “malicious” punishes restricted browsers, outages, and integration mistakes. A common starting posture is to preserve ordinary controls, defer a high-impact action, or request a reversible step-up while the cause is investigated.

## The five-tier risk model

Noxtica's public web response uses five risk tiers:

| Tier       | Current score range | Interpret as                                     | Example starting action—not a default guarantee      |
| ---------- | ------------------: | ------------------------------------------------ | ---------------------------------------------------- |
| `minimal`  |                0–19 | Little risk evidence in the available assessment | Allow under normal application controls              |
| `low`      |               20–39 | Minor or explainable anomalies                   | Allow and observe                                    |
| `medium`   |               40–59 | Mixed or incomplete suspicious evidence          | Observe, queue, or use low-friction step-up          |
| `high`     |               60–79 | Strong suspicious evidence                       | Challenge, hold, or review                           |
| `critical` |              80–100 | Multiple or strong reason families agree         | Strong challenge or block only under reviewed policy |

The response ranges provide a consistent integration vocabulary. They are not a promise that one threshold fits every tenant or that a tier will never change meaning under a versioned service contract. Use Backoffice distributions and your own confirmed outcomes to select actions.

### Configure policy by surface

| Surface                       | What to configure                                                    | Why it differs                                      |
| ----------------------------- | -------------------------------------------------------------------- | --------------------------------------------------- |
| Public content                | Observe, rate limit, or apply agent-specific policy                  | The action is usually reversible and low value      |
| Signup or promotion           | Detect repeated or automated attempts; step up before granting value | Shared devices and legitimate retries are common    |
| Login                         | Combine device familiarity with authentication and account context   | A new device is not proof of takeover               |
| Checkout                      | Combine assessment with transaction and account controls             | The cost of a false denial and fraud both matter    |
| Recovery or credential change | Require stronger authentication when risk or confidence warrants it  | The operation is high impact even for known devices |

Start in shadow or observe-only mode where available. Record which action _would_ occur, compare it with confirmed outcomes and customer-friction measures, and promote only the reviewed route policy.

## Confidence is a separate axis

Risk answers “how concerning is the available evidence?” Confidence answers “how much usable evidence supported that assessment?” They are not substitutes.

| Risk | Confidence | Safer interpretation                          | Possible response                                          |
| ---- | ---------- | --------------------------------------------- | ---------------------------------------------------------- |
| Low  | High       | Available evidence is consistently ordinary   | Allow under normal controls                                |
| Low  | Low        | Little concern was seen, but little was known | Preserve normal controls; avoid granting extra trust       |
| High | High       | Strong concern with substantial corroboration | Challenge, hold, review, or apply a reviewed block rule    |
| High | Low        | Concern exists but evidence is incomplete     | Reversible step-up or review; investigate missing evidence |

Confidence can be affected by collection mode, browser support, page timing, caching, consent choices, optional-module status, or integration errors. Do not infer a person's behavior or disability from a confidence value.

## The reasons are the audit trail

Named reasons tell an authorized operator which public evidence family influenced the result: for example automation, consistency/tampering, network/infrastructure, privacy-browser handling, device integrity, or interaction context. They help support and fraud teams answer “why did this assessment move?” without exposing the hidden test or its weight.

Use reasons to:

- distinguish a potentially explainable anomaly from corroborated abuse;
- find the relevant [threat category](https://noxtica.com/docs/threat-categories/);
- compare an individual record with its domain's population;
- choose a better step-up or allow treatment for approved automation;
- label a confirmed outcome through the supported customer surface; and
- investigate policy regressions after a browser, traffic, or configuration change.

Do not use reasons to:

- turn one flag into a permanent deny list;
- infer protected or sensitive traits;
- reproduce or probe the detection mechanism;
- assume two matching reasons prove the same person or actor; or
- promise a customer that the result is error-free.

## Calibrate with your own outcomes

1. **Define the unit:** signup, login, transaction, request, account change, or moderation case.
2. **Define known outcomes:** confirmed abuse, confirmed legitimate, challenge passed, appeal upheld, chargeback, review disposition, or another defensible label.
3. **Run observe-only:** collect enough representative traffic for the routes and cohorts you will govern.
4. **Compare:** inspect risk, confidence, reasons, unknown/error rates, customer friction, and action volume.
5. **Choose thresholds:** start with reversible actions and route-specific exceptions.
6. **Review after launch:** watch drift, challenge completion, abandonment, support contacts, reversals, and missed abuse.
7. **Change deliberately:** record the rationale, reviewer, effective time, and rollback condition.

Quality or calibration surfaces may be plan- or role-gated. If your account does not expose them, agree on the supported labeling and review process with your Noxtica contact before enforcement.

## Calibration over verdicts

The short version:

1. A risk tier is an ordered measurement, not identity or intent.
2. Confidence expresses evidence coverage, not safety.
3. Reasons make the outcome reviewable without publishing sensitive detection mechanics.
4. Different customer journeys need different actions.
5. Unknown, error, and low-confidence states need explicit safe handling.
6. Your labeled traffic and customer-friction data—not an unsupported universal metric—determine whether policy works.

## Eligibility and limitations

Core risk fields are available with an activated collection integration. Advanced scoring endpoints, quality/calibration tooling, attestation, behavioral, agent, identity, investigation, and enforcement modules can require plan entitlement, tenant or domain activation, operator permissions, quota, a supported client, or legal-basis review.

Calibration reduces hidden uncertainty; it does not eliminate model error, adversarial adaptation, incomplete data, or traffic drift. Exact false-positive rates, detection rates, latency, threshold stability, and change-notice commitments apply only when defined by a current measurement record or customer contract.

## Related reading

- [Threat categories](https://noxtica.com/docs/threat-categories/) — interpret the public reason families.
- [Detection signals](https://noxtica.com/docs/detection-signals/) — understand evidence layers and missing data.
- [Engineering principles](https://noxtica.com/docs/principles/) — the operating constraints for rollout and review.
- [Use cases](https://noxtica.com/docs/use-cases/) — route-specific reference patterns.
- [Customer capability reference](https://noxtica.com/docs/features/#risk-and-decisioning) — customer surfaces, outputs, eligibility, and limits.

---

Source: https://noxtica.com/docs/hunter/extension/
Markdown: https://noxtica.com/docs/hunter/extension/index.md
Last updated: 2026-10-27

# Hunter browser extension

noxtica Hunter is a browser extension that shows which scripts on one web page you choose to audit read your browser's fingerprint-related features, such as canvas, WebGL, audio, navigator and screen properties, fonts and timing. The analysis runs on your device.

Developers, security reviewers and privacy teams use it. You start every audit by hand. Sharing a report with your Noxtica workspace is a separate, optional step that is off by default.

## What it is

Availability: depends on your organisation and the modules enabled for it; ask your account team.

Hunter is not an automatic scanner. Nothing is observed until you press **Start audit** or **Quick look** for the current tab. This page describes the extension as built from source. How your organisation receives a build, and for which browsers, is arranged with your account team.

### What an audit gives you

- A **rating**: the share of fingerprint features the page touched, compared with published thresholds. The thresholds are marked Provisional until they are calibrated, so read the level as indicative.
- A **risk score** from 0 to 100 with a level (low, medium, high or critical) and the reasons behind it.
- **Detections** by feature area, with the calling script for each API.
- **Vendors** recognised from script addresses, code patterns and network traffic.
- **Script sources**, marked first party or third party.
- **Network findings**: requests whose payload looked like fingerprint data. Hunter keeps field names and keywords, never values.
- **Bot-signal observations** and **Environment context** labels (for example a privacy browser or developer tools) that explain why a reading may look unusual.

The report page says it is advisory: Hunter observes from inside the page, and a page can interfere with what it sees. Treat a report as a signal, never as evidence of intent.

### Two ways to run

| Mode | What happens | Limit |
| --- | --- | --- |
| Start audit | Asks once for access to that one site, reloads the page so it sees every call from the start, records until the timer ends or you press **Stop**, then gives the access back | Default 30 seconds; whole seconds from 1 to 600 |
| Quick look | No permission prompt and no reload; records from now on | Calls made before you pressed the button are missed ("Late attach") |

Hunter audits only `http` and `https` pages. It refuses to instrument a page that already runs the Noxtica SDK, so it cannot interfere with that page's integrity signals. Only one audit can run at a time.

### Permissions

| Permission | Why |
| --- | --- |
| `activeTab` | Lets Quick look run on the current tab after you click the extension |
| `scripting` | Installs the observer in the one origin you chose and removes it when the audit stops |
| `storage` | Keeps audit state, your preferences and the reports you save |
| `sidePanel` | Shows the live view and report next to the page |
| Optional host access to `http://*/*` and `https://*/*` | Requested at run time for one origin at a time, on your click |

The extension declares no static host permission and no always-on content script. It does not request `tabs`, `webRequest`, `debugger`, `cookies` or `history`. The minimum Chrome version is 116.

### What is recorded and what is not

The About page states that Hunter records which APIs were called, how often and by which script address (origin and path only). It states that Hunter never records values: no pixels, text, coordinates, clipboard or storage contents, and no request bodies. Reports are kept only if you save them: up to 50, for 30 days, in the browser's extension storage. You can delete one report or all of them at any time.

For how Noxtica handles data in general, see [Privacy](https://noxtica.com/privacy/) and [Security](https://noxtica.com/docs/security/).

### Optional: send one report to your Noxtica workspace

Some builds can send a report you choose to your organisation's Noxtica workspace. This is off by default and never automatic. A build without this feature shows no upload control and says "This build does not upload anything".

Sending needs all of the following:

1. You turn sending on in Options and allow the browser to give Hunter access to the Noxtica ingestion endpoint (`https://ingest.noxtica.com`).
2. A workspace administrator has created a short-lived upload token in Backoffice and you have pasted it into Hunter.
3. You press **Send** on a specific report after you have seen a preview of the exact JSON.

What is sent: the report you previewed, which holds the origin and path of the audited page and of its scripts, API names and counts, and a vendor and risk summary. Query strings and fragments are removed when the report is built, and the ingestion endpoint refuses a report that still contains one. What is never sent: cookies, page content, keystrokes and API argument values. If a path itself contains a name or other identifier, it is part of the report, so read the preview before you press Send.

The token names your organisation and the administrator who created it. Every report sent with it is stored under that organisation and linked to that administrator. The token is kept in the browser's session storage for that session and used for nothing else. Reports are stored in the EU and kept for 30 days; administrators can remove them sooner in Backoffice. See [Hunter reports in Backoffice](https://noxtica.com/docs/hunter/reports/).

## Prerequisites

- A Hunter build from your account team, in a Chromium-based browser at version 116 or later.
- A normal website (`http` or `https`) open in a tab. New-tab pages, `chrome://`, `about:` and browser store pages cannot be audited.
- For sending reports: a build that includes sending, a workspace administrator with the Hunter Reports page available (see the Backoffice page), and permission to let the extension reach `https://ingest.noxtica.com`.

## Steps

### 1. Run an audit

1. Open the website you want to audit in a tab.
2. Click the Hunter icon in the toolbar. If you cannot see it, open the extensions menu and pin Hunter.
3. Optionally set **Audit length (seconds)**.
4. Press **Start audit** and accept the browser prompt for access to that site. The page reloads.
5. Use the page normally. Press **Stop** when you are done, or wait for the timer.

For a quick read without a reload, press **Quick look** instead.

### 2. Open the report

Press **View report** in the popup or **Open side panel**. The report page has the sections Summary, Risk and rating, Detections, Vendors, Script sources, Network, Bot-signal observations, Environment context, Spy health, Frames and Errors.

Open the Hunter panel in the browser developer tools before you start an audit if you also want script-code analysis. It works only while that panel is open, and script text is analysed and then discarded; only pattern names, categories and counts are kept.

### 3. Export, save or delete the report

- **Export JSON**, **Export HTML** or **Export text** downloads the report. The HTML file is self-contained and loads nothing.
- **Save report** adds it to your saved reports (up to 50, kept for 30 days). **Saved reports** lists them with their expiry date and lets you view, delete one or **Delete all**.
- Under Options you can set a default audit length and turn on **Save finished reports automatically** (off by default).

### 4. Send a report to your workspace (optional)

1. A workspace administrator creates a token: Backoffice → Session Insights → Hunter Reports → **Create upload token**, picks a lifetime (5 minutes, 15 minutes, 1 hour, 4 hours or 12 hours) and copies the token. See [Hunter reports in Backoffice](https://noxtica.com/docs/hunter/reports/).
2. In Hunter, open Options → **Send reports to your organisation (optional)**. Press **Turn on sending to this endpoint** and allow the browser prompt.
3. Paste the token under **Report token** and press **Use this token**. Hunter refuses a collector secret key (`sk_…`) and any token that is not a Hunter report token.
4. Open a report and press **Send to my organisation…**. Read **Exact JSON that will be sent**, then press **Send this report**.

To stop, press **Turn off sending and remove access**, or **Forget token**. Forgetting a token removes it from the browser; it stays valid until it expires.

Limits at the ingestion endpoint (defaults): 512 KiB per report after decompression, 200 reports per organisation per day and one report per 5 seconds per token. Hunter tries a send up to 3 times for transient failures.

## Verify it works

- After an audit, the popup shows **Last audit** with a live or finished result and the reason it ended (you stopped it, the audit length ended, the tab closed, the browser restarted or the tab moved to another site).
- The toolbar button shows the rating level, and its tooltip lists the touched and aggressive feature counts.
- The report page shows the Summary with the page, start time, duration, mode (Audit or Quick look) and a Report ID, and **Export JSON** shows exactly what was recorded.
- After **Save report**, the popup says "Saved. Saved reports: N".
- After a send, the report page says "Sent. Your organisation's Noxtica workspace stored report <id> until <date>", and the saved report shows "Sent <time>". The report then appears in Backoffice → Hunter Reports.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| "Hunter cannot start on this tab" or "Open a normal website (http or https) tab first" | The tab is a browser page, a store page or not a website | Open an `http` or `https` page. |
| "Refused: This page already runs the Noxtica SDK" | Hunter does not instrument pages that Noxtica already instruments | Audit a page without the Noxtica SDK. |
| "Permission denied: Hunter needs site access for this origin" | You declined the browser prompt | Press **Start audit** again and accept, or use **Quick look**. |
| "Hunter could not register its page scripts", "could not reload the tab" or "could not attach to this page" | The page or browser blocked the observer | Try again; use **Quick look**; note that nothing was recorded. |
| "An audit is already running on this page. Stop it first." | One session at a time | Press **Stop**, then start again. |
| "The Hunter background could not be reached" | The extension background is stopped | Reload the extension and try again. |
| Counts look low and a "Late attach" notice appears | Quick look attached after the page made its calls | Use **Start audit**. |
| "Rating not computed yet" | The build has no rating taxonomy | Not a good or bad result; use a build that includes it. |
| "Export refused: the report did not pass validation" | The report failed Hunter's own check | Run the audit again. |
| "Saved reports could not be read" | Extension storage problem | Reload the extension. |
| "Sending is off. Turn it on in Options first." | Sending is not turned on | Complete step 4.2. |
| "No token is stored, so nothing was sent" or "The stored token has expired" | No token, or it expired | Create a new token in Backoffice and paste it. |
| "That is a collector secret key (sk_…), not a report token" | Wrong credential pasted | Paste the upload token from Hunter Reports, never a server API key. |
| "The Noxtica ingest endpoint did not accept the token (401)" | Token expired or invalid | Create a new token. |
| "The Noxtica ingest endpoint refused this organisation right now (403)" | Noxtica refused the organisation at that moment and stored nothing | Try again later. If it persists, ask your account team. |
| "This endpoint does not accept Hunter reports (404)" | Report upload is not switched on at the endpoint | Ask your account team. |
| "refused the report's strict check (422)" | The report has a query string, a fragment, an unknown field or an unknown version | Run the audit again with an up-to-date build. |
| "This report is larger than the 512 KiB limit" or "(413)" | Report too large | Audit a smaller page or shorten the audit. |
| "accepts one report per token every few seconds (429)" | Rate limit | Wait a moment and send again. |
| "Your organisation has reached its daily report limit (429)" | Daily limit | Try again tomorrow. |
| "Noxtica already holds a different report with this id (409)" | Report id clash | Run a new audit and send that report. |
| "could not reach the Noxtica ingest endpoint" or "did not answer in time" | Network or server problem | Check the connection and try again; sending again is safe. |

## Related

- [Hunter reports in Backoffice](https://noxtica.com/docs/hunter/reports/) for the list, detail, download and delete views and for creating upload tokens.
- [Spot captures](https://noxtica.com/docs/hunter/spot/) for operator-started recordings.
- [Browser SDK troubleshooting](https://noxtica.com/docs/sdk/troubleshooting/) if Hunter refuses a page that runs the Noxtica SDK.
- [Privacy](https://noxtica.com/privacy/) and [Security](https://noxtica.com/docs/security/) for data handling.

---

Source: https://noxtica.com/docs/hunter/reports/
Markdown: https://noxtica.com/docs/hunter/reports/index.md
Last updated: 2026-10-27

# Hunter reports in Backoffice

Hunter Reports is the Backoffice page where page audits that your team sent from the [Hunter browser extension](https://noxtica.com/docs/hunter/extension/) land. A workspace administrator creates upload tokens and can delete reports. Analysts and administrators can read them.

Nothing is uploaded automatically. A report arrives only when someone pastes an upload token into the extension and presses Send on that report.

## What it is

Availability: depends on your organisation and the modules enabled for it; ask your account team.

The page lives under Backoffice → Session Insights → Hunter Reports. It does not appear in the sidebar, and its address answers "not found", until Hunter report upload is switched on for your environment. When it is not switched on, Backoffice shows "Hunter report upload is not switched on yet".

### Who can do what

| Action | Role | Step-up MFA |
| --- | --- | --- |
| List reports, open a report, download the JSON | Analyst or higher (`view.hunter`) | No. Every detail read and download is recorded in the audit log without copying the report content. |
| Create an upload token | Administrator (`manage.hunter`) | Yes |
| Delete one report, or all reports from one reporter | Administrator (`manage.hunter`) | Yes |

### What a report contains

A report lists which scripts used which browser features during one page load in one browser. The page states that a report never contains page content, the values those features returned, or anything that identifies a visitor. It names the reporter: the administrator who created the token that was used to upload it.

A high rating describes what that page did at that time. It is not a verdict about the site, and a page that behaves differently on other visits can look quieter.

### Retention

Uploaded reports expire 30 days after upload. The list shows each report's expiry in its "Deleted after" column, and the detail page counts the days left. Administrators can delete a report earlier. This retention applies to Hunter reports only; identity-verification data follows a different rule, described in [Verification data: storage, access and deletion](https://noxtica.com/docs/identity-verification-data/).

### What the audit log records

Backoffice writes an audit row for each of these, without copying report content or the token:

| Event | Detail recorded |
| --- | --- |
| Token created | The token's expiry and requested lifetime |
| Report read or downloaded | The report ID and counts only |
| Delete requested | Who asked, and which report. The row is written first; if it cannot be written, nothing is deleted. |
| Delete confirmed | The outcome of the deletion |

The token itself is never stored, logged or audited. If the audit row for a new token cannot be written, no token is handed out.

### What the list and the detail show

| Item | Meaning |
| --- | --- |
| Risk score | A score from 0 to 100 that weighs the vendors and behaviours seen on that page load, with a level of Low, Medium, High or Critical. It is independent of the feature rating. |
| Feature rating | The share of browser features the page touched, compared with published thresholds. A "Provisional thresholds" badge appears while the thresholds are not calibrated. |
| Mode | Audit, Quick look or Lab |
| Party | Whether a script is first party or third party |
| Suspicion | The suspicion level of a script's code patterns |

## Prerequisites

- Hunter report upload switched on for your environment, and a Hunter build that includes sending. Ask your account team.
- Analyst role to read reports; administrator role to create tokens and delete.
- A device that can complete step-up MFA, for tokens and deletions.

## Steps

### 1. Create an upload token

1. Backoffice → Session Insights → Hunter Reports → **Create upload token**.
2. Pick a **Lifetime**: 5 minutes, 15 minutes, 1 hour, 4 hours or 12 hours. The default is 12 hours.
3. Press **Create token** and confirm the fresh verification code prompt.
4. Press **Copy upload token**.

The token is shown once. Close the window and you need to create another. The token lets one browser upload reports to this workspace until it expires. It cannot read, list or delete anything.

### 2. Give the token to the person who will send reports

In the Hunter extension: Options → **Send reports to your organisation (optional)** → paste it under **Report token**. See [Hunter browser extension](https://noxtica.com/docs/hunter/extension/). Every report sent with the token is stored under your workspace and linked to the administrator who created it, so create tokens for people you trust and with a short lifetime.

### 3. Find a report

The list shows newest first, with Page, Risk score, Feature rating, Uploaded, Deleted after, Size and Actions. Open **Filter reports** to narrow it:

- **Page contains**, for example `example.com/checkout`.
- **Risk score** and **Feature rating**: Low, Medium, High (risk also has Critical).
- **Uploaded from** and **Uploaded until**.

Press **Show more reports** to load another page. A page holds 50 reports by default and at most 100.

### 4. Read a report

Open a row. The detail page has these sections: Risk score, Feature rating, Capture health, Scripts observed, Vendors recognised, Network and script findings, Activity by feature area and Data versions. Capture health tells you whether the extension could observe every feature area; a failed area can make a page look quieter than it is. If a report uses a format the page cannot display, the summary stays correct and you can download the JSON.

### 5. Download the JSON

Press **Download JSON**. The file is named `hunter-report-<id>.json`. The response carries the header `X-Hunter-Payload-Sha256`, the digest stored with the report, so you can check that the file you hold is the file Noxtica stored.

### 6. Delete reports

- On a report, press **Delete**, then **Delete report**. The report is permanently removed from the workspace.
- On a report, press **Delete all reports from this reporter** to remove every report uploaded with a token created by that administrator.

A report uploaded in the last few minutes can take a few minutes to disappear completely; if it reappears, delete it again. Each deletion is recorded in the audit log. See [Audit log and data export](https://noxtica.com/docs/security/audit-log-and-exports/).

## Verify it works

- A new token appears with "Expires <time>" and a copy button.
- After a send from the extension, the report is listed with its page, risk score, rating, upload time and expiry. The extension shows "Sent. Your organisation's Noxtica workspace stored report <id> until <date>".
- The downloaded file opens as JSON and its report schema is `noxtica.hunter.report/v1`.
- After a delete, the page shows "Report deleted." or "Deleted N reports from this reporter."

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| Hunter Reports is not in the sidebar, or the page says not found | Hunter report upload is not switched on, or you lack the analyst role | Ask your account team; check your role under Users. |
| "Hunter report upload is not switched on yet" | The environment does not accept reports | Ask your account team. |
| Creating a token fails with a verification prompt | Step-up MFA is required | Enter the fresh verification code. |
| Token creation is refused as unavailable | Token signing is not configured for your environment | Ask your account team. |
| The extension says the token expired or was not accepted (401) | Lifetime ended | Create a new token. |
| List says "No reports have been uploaded yet" | Nobody has pressed Send, or the token was not used | Create a token and send a report from the extension. |
| List says "No reports match these filters" | Filters are too narrow | Widen the date range or press **Clear**. |
| "This report uses a format this page cannot display" | The report was made with a newer or different extension build | Download the JSON; the summary is still correct. |
| A deleted report is still listed | It was uploaded within the last few minutes | Wait a few minutes and delete it again. |
| A report is gone before you expected | It reached its 30-day expiry | Download reports you need before they expire. |

## Related

- [Hunter browser extension](https://noxtica.com/docs/hunter/extension/) for audits, the preview and sending.
- [Spot captures](https://noxtica.com/docs/hunter/spot/) for operator-started recordings.
- [Roles and permissions](https://noxtica.com/docs/security/roles-and-permissions/) for analyst and administrator capabilities.
- [Audit log and data export](https://noxtica.com/docs/security/audit-log-and-exports/) for the records of reads, tokens and deletions.
- [Privacy](https://noxtica.com/privacy/) and [Security](https://noxtica.com/docs/security/) for data handling.

---

Source: https://noxtica.com/docs/hunter/spot/
Markdown: https://noxtica.com/docs/hunter/spot/index.md
Last updated: 2026-10-27

# Spot captures

Spot is a browser extension that records one tab or one desktop or window capture when an operator explicitly starts it. A tab capture adds bounded developer context, so your team can reproduce a problem seen in real-user monitoring or session replay. Captures upload to Noxtica, and Backoffice plays them back.

Support engineers and developers record. A workspace administrator connects the extension and manages sharing.

## What it is

Availability: depends on your organisation and the modules enabled for it; ask your account team.

Nothing records until an operator clicks **Start capture** in the extension. Each click creates one explicit capture. Backoffice never starts a capture. This page describes the extension as built from source; how your organisation receives a build is arranged with your account team.

| Source | What is recorded |
| --- | --- |
| Current tab + developer context | Video of the tab, plus console messages, network metadata, clicks and navigation |
| Desktop / window video only | Video only |

### Developer context, bounded

- Console messages: the levels debug, info, log, warn and error. At most 10 arguments per message, each cut to 512 characters.
- Network metadata for fetch and XHR calls, with request routes reduced to origin and path.
- Clicks: the position as a fraction of the window and the element tag name.
- Navigation: origin and path.
- Request and response bodies, headers, query strings and URL fragments are not captured.

The instrumentation is added to the tab only for the duration of one capture. If it cannot be armed, the capture stops instead of recording incomplete context.

### Storage and limits

Playback is WebM only; Noxtica stores and plays the captured WebM as it was recorded. These are the defaults; bounds can change and Backoffice shows the values in force for your workspace.

| Limit | Default |
| --- | --- |
| Extension token lifetime | 12 hours (range 5 minutes to 24 hours) |
| One upload chunk | 8 MiB |
| One capture | 64 MiB and 64 chunks |
| Upload volume per workspace per day | 512 MiB |
| Capture retention | 7 days (range 1 to 90 days) |
| Share link lifetime | 7 days (range 5 minutes to 30 days), never longer than the capture's own retention |

### Who can do what

| Action | Role |
| --- | --- |
| List captures and open one | Analyst or higher (`view.spot`) |
| Play the recording and read the events | Administrator (`view.spotPayload`) |
| Connect the extension, create or revoke share links, delete a capture | Administrator (`manage.spot`) |

## Prerequisites

- Spot capture switched on for your organisation, and the surface enabled for your domain. If capture is not switched on, Backoffice says "Spot capture is not armed on this deployment". If Backoffice cannot reach the capture service it says "Spot is not connected".
- The Spot extension installed in a Chromium-based browser, version 116 or later.
- An administrator to create the extension token.
- A regular website (`http` or `https`) in the tab. Browser pages cannot be recorded.

## Steps

### 1. Create a short-lived extension token

1. Backoffice → Session Insights → Spot Captures → **Connect extension**.
2. Press **Copy extension token**. Backoffice says when the token expires.

Paste this short-lived token into the extension. Every capture still needs a separate Start click.

### 2. Connect the extension

1. Open the Spot popup.
2. Leave **Collector URL** as `https://collect.noxtica.com`, unless your account team gives you another address.
3. Paste the token under **Short-lived extension token**.

### 3. Record a capture

1. Choose the **Capture source**: Current tab + developer context, or Desktop / window video only.
2. Press **Start capture**. For a desktop capture, choose the screen or window in the browser dialog.
3. Reproduce the problem.
4. Press **Stop and upload**. Keep the extension loaded while chunks upload.

If an upload fails, Spot stops recording and keeps the pending chunks. Press **Retry upload**, which appears in the popup, before you start another capture.

### 4. Review a capture

Backoffice → Session Insights → Spot Captures. The list shows each capture with Kind (Tab or Desktop), Duration, Size, Age and Sharing. A capture has a state: Recording, Complete, Failed, Expired or Deleted. Open a row, then press **Play**.

For a tab capture, the "Synchronized developer context" table lists the captured events in time with the video. A desktop capture has video only.

### 5. Share a capture

1. Open the capture and find **Share access**.
2. Optionally enter **Recipient or purpose (optional)**. The note is visible to workspace operators, not to viewers of the link.
3. Press **Create expiring link** and copy it with **Copy share link**.

Anyone who has the current link can watch the recording and read its events until the link expires or you revoke it. Backoffice shows the link only once, when you create it. Press **Revoke link** to cut access at once; the capture itself is kept. A capture has one active link at a time.

### 6. Delete a capture

Press **Delete**, then **Delete capture**. The recording, captured events and every active share link are permanently removed.

## Verify it works

- The popup status moves to "Recording the current tab and developer context…" or "Recording the selected desktop or window…", then to "Ready. Nothing is being recorded." after upload.
- The capture appears in Spot Captures with state Complete.
- **Play** plays the WebM, and the events table follows it for tab captures.
- A created link shows "Expires <time>" and the capture shows Shared.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| "Add a collector URL and short-lived extension token before starting." | No token or URL in the popup | Create a token (step 1) and paste it. |
| "This browser page cannot be recorded." | The tab is a browser page | Open a regular website. |
| "No desktop or window was selected. Nothing was recorded." | The picker was cancelled | Start again and choose a source. |
| "The tab instrumentation could not be armed, so the capture was stopped" | The page blocked the instrumentation | Try another tab or page. |
| "The previous upload failed. Retry it before starting another capture." | Upload failed | Press **Retry upload**. |
| Upload is refused with a quota message | Capture, chunk or daily upload limit reached | Record a shorter capture or try tomorrow. |
| "Spot capture is not armed on this deployment." | Capture is not switched on | Ask your account team. |
| "Spot is not connected" | Backoffice cannot reach the capture service | Ask your account team. |
| "Unable to mint an extension token." | A temporary fault, or your role | Retry as an administrator; contact support if it persists. |
| "This capture has expired." | Its retention ended | Record again; the recording is gone. |
| "The recording bytes are missing." | The stored video is unavailable | Ask your account team to check storage. |
| "The captured events are missing." or "Events could not be read" | The events object is unavailable | Playback can still work; record again if you need the events. |
| Sharing link no longer works | It expired or was revoked | Create a new link. |

## Related

- [Hunter browser extension](https://noxtica.com/docs/hunter/extension/) for the page-audit extension.
- [Session replay: setup, masking and playback](https://noxtica.com/docs/observability/session-replay/) for the replay product that Spot complements.
- [Roles and permissions](https://noxtica.com/docs/security/roles-and-permissions/) for analyst and administrator capabilities.
- [Privacy](https://noxtica.com/privacy/) and [Security](https://noxtica.com/docs/security/) for data handling.

---

Source: https://noxtica.com/docs/pulse/overview/
Markdown: https://noxtica.com/docs/pulse/overview/index.md
Last updated: 2026-10-27

# Noxtica Pulse: endpoint telemetry overview

Noxtica Pulse is endpoint telemetry and integrity for an organisation's own applications, such as a game or a workforce program. A small desktop client on the user's computer reports what your published configuration allows, and Backoffice shows you what is registered, who is enrolled and which configuration is live.

This page is for the administrator or privacy owner who will configure Pulse and for the engineer who connects it to an account system. The other two Pulse pages cover [Backoffice configuration](https://noxtica.com/docs/pulse/backoffice/) and [detections, response, devices and privacy](https://noxtica.com/docs/pulse/detections-and-privacy/).

## What it is

Availability: In development.

Pulse is not released for deployment to customer machines. This page describes the surfaces as they exist for organisations where Pulse is provisioned. It does not offer an installer download or a rollout schedule, and it makes no commitment about operating systems, signing or distribution; agree those with your account team.

### The pieces

| Piece | Who uses it | What it does |
| --- | --- | --- |
| Backoffice → Noxtica Pulse | Your administrators | Register applications, author profiles, publish signed configuration bundles, run staged rollouts, review detections and devices, read privacy settings and usage |
| Desktop client | The person using your application | A background service, a tray app and a command-line tool (`pulse-ctl`). It follows the configuration your bundle sets, shows what Pulse sees, and has a local kill switch |
| Player site at `pulse.noxtica.com` | The person using your application | Register and sign in, authorise the desktop app, see devices and consents, export or delete their data, view and appeal detections |
| Server API | Your backend | Look up a player's status, issue link codes, unlink, and reverse response hints, authenticated with your server API key |

The player site is a separate site from Backoffice. Tenant staff configure Pulse in Backoffice, never on the player site. While Pulse is in development, treat the player site as available only to organisations where Pulse is provisioned.

### How configuration reaches a device

1. You register an application. Its slug is the join link every device enrols with.
2. You author a profile for it: telemetry, privacy and retention.
3. You publish the profile. Backoffice signs it as a configuration bundle with the next revision number.
4. Devices pull the bundle on their next poll and verify its signature. A device keeps its last good bundle if a later one is invalid, rolled back or oversize.
5. The initial revision of an application goes live for every device at once. Later revisions roll out ring by ring while a health gate stays green.

A published revision can never be edited or deleted. To undo one, you roll back, which publishes the older content again as a new, higher revision.

### Telemetry lanes

Devices send telemetry to the ingestion service on `ingest.noxtica.com`. You do not call these routes yourself.

| Lane | Route | Body limit |
| --- | --- | --- |
| Event batches | `POST /pulse/v1/events` (`pulse.batch/v1`) | 256 KiB compressed, 1 MiB decompressed, 500 events |
| Metrics | `POST /pulse/v1/otlp/metrics` | 1 MiB compressed, 4 MiB decompressed, 500 points |
| Logs | `POST /pulse/v1/otlp/logs` | 1 MiB compressed, 4 MiB decompressed, 500 records |
| Heartbeat | `POST /pulse/v1/heartbeat` | 16 KiB |

These lanes are switched off until Pulse is provisioned. Each device authenticates with a short-lived access token that is bound to its own key. Per-device limits default to 60 requests and 1 MiB of compressed uplink per minute. Limits can change; Backoffice → Pulse → Usage shows what the service accepted.

### Who sees what

| Role | Can do |
| --- | --- |
| Viewer or higher (`view.pulse`) | Read overview, applications, profiles, bundles, rollouts, devices, privacy, usage |
| Analyst or higher (`view.pulseEvidence`) | Open a detection or response decision, which shows per-device evidence. Every access is recorded. |
| Administrator (`manage.pulse`, `manage.pulseRules`, `manage.pulseResponse`) | Write: register and archive applications, save and publish profiles, roll back, halt and resume rollouts, revoke devices, review detections, accept the response addendum. Every write needs step-up MFA and is audited. |

## Prerequisites

- Pulse provisioned for your organisation: the platform switch is on, your workspace is armed for Pulse and entitled to it. Until then the sidebar group is hidden or Backoffice shows "Pulse is not enabled for this tenant. Ask your Noxtica contact to enable it; nothing is collected until then."
- Viewer role or higher in Backoffice to look; administrator for changes.
- For the server API: a server API key with the scope `read:pulse` or `write:pulse`. Create it in Backoffice → Integrations & API → API & SDK. See [Authentication](https://noxtica.com/docs/api/authentication/).
- Legal and privacy review inside your organisation before devices enrol. The pages in this section list controls; they are not legal advice. See [Privacy](https://noxtica.com/privacy/) and [Security](https://noxtica.com/docs/security/).

## Steps

### 1. Check that Pulse is available to you

Open Backoffice → Noxtica Pulse → Pulse. If you see "Pulse is not enabled for this tenant", ask your account team. If the Noxtica Pulse group is missing from the sidebar, your role or the platform setting hides it.

### 2. Read the overview

The Pulse overview shows these cards: Active applications, Archived applications, Active enrolments, Revoked enrolments; Fleet health (Devices reporting, Crash-free sessions, Open detections, Active rollouts); Current revision per application; Rollouts in progress; Attestation level mix; Bundle signer; Device seats and Recent activity. Groups with fewer than 5 devices are hidden from the fleet figures to protect individuals, so a small fleet can look under-counted.

A device seat is one device with an active enrolment, however many applications it is enrolled in. A new device over the seat limit is refused at enrolment; revoking a device frees its seat.

### 3. Configure Pulse in order

Work through [Pulse in Backoffice: applications, profiles, bundles and rollouts](https://noxtica.com/docs/pulse/backoffice/): register an application, create and validate a profile, publish it, and follow the rollout.

### 4. Set review and privacy policy before devices enrol

Read [Pulse detections, response, devices and privacy](https://noxtica.com/docs/pulse/detections-and-privacy/): who reviews detections, how players appeal, what the response ladder may do, and what the privacy page shows.

### 5. Optional: link players to your own accounts

Your backend can ask for a one-time link code for one of its own users and hand the returned address to that person. The person signs in to the player site, sees what your organisation will see, and approves or denies. See the server API section of the detections page.

## Verify it works

- The Pulse overview loads without "Pulse is not enabled" and lists your registered application under Current revision per application.
- After a device enrols, Active enrolments rises and the device appears under Pulse → Devices.
- After a rollout, the Rollouts page shows the revision, the stage and the last health check.
- Pulse → Usage shows counters per UTC day once devices report.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| Noxtica Pulse is missing from the sidebar, or a Pulse address answers "not found" | The platform switch is off, or your role is below viewer | Ask your account team and check your role. |
| "Pulse is not enabled for this tenant" | Your workspace is not armed for Pulse or lacks the entitlement | Ask your Noxtica contact. |
| "Could not load Pulse" | A temporary fault | Retry; contact support if it persists. |
| Fleet health says "Not enough data: every group has fewer than 5 devices" | Small groups are hidden | Wait for more devices; this is a privacy protection. |
| "The warehouse could not be read right now." | The analytics store is unavailable | Retry later; the figures that did load stay visible. |
| A device is refused at enrolment | The seat limit is reached | Revoke a device you no longer use or ask your account team. |
| Server API answers `insufficient_scope` or `tenant_not_armed` | Key lacks the scope, or the workspace is not armed | Create a key with `read:pulse` or `write:pulse`; ask your account team. |

## Who it fits

These are questions Pulse is planned to help answer. Fit depends on what the finished scope turns out to be.

- **Is the application behaving as expected?** Teams could see whether their application runs as expected on a device, within the signals the tenant enables.
- **Is the problem on the device side?** Teams could separate a poor device connection from a problem in their own service.
- **Which flags deserve human review?** Teams could review flagged signals and the evidence behind them before any decision about an account. See [Human review is the default](https://noxtica.com/docs/pulse/detections-and-privacy/#human-review-is-the-default).

## How teams connect

Tenants and device owners connect to Pulse through the surfaces in [The pieces](https://noxtica.com/docs/pulse/overview/#the-pieces).

- **Tenants.** Tenants would configure signals, notices and review workflows in the Noxtica console. A tenant would choose which signals to enable for its own application and publish a notice explaining what is collected and why. See [Pulse in Backoffice](https://noxtica.com/docs/pulse/backoffice/) and [Pulse detections, response, devices and privacy](https://noxtica.com/docs/pulse/detections-and-privacy/).
- **Device owners.** Device owners would sign in with their own Noxtica account on the device, read the notice, and accept or decline optional purposes. They are planned to be able to switch purposes off, withdraw consent, export their data and request erasure. Flagged detections would come with a reason and a way to appeal.

## Limits

Read [Who it fits](https://noxtica.com/docs/pulse/overview/#who-it-fits) and [How teams connect](https://noxtica.com/docs/pulse/overview/#how-teams-connect) as a description of intent.

- Pulse is in development. Nothing on this page is a commitment on scope or date.
- Signals would be indicators, not proof. They are probabilistic and can be wrong. A client running as an ordinary program cannot observe every kind of tampering. The tenant decides what to do, and no protection outcome is promised.
- The client is planned to notify the device owner and report signals. It is not planned to end sessions or stop programs on the device. See [Configure the response ladder](https://noxtica.com/docs/pulse/detections-and-privacy/#5-configure-the-response-ladder).
- Customers would be responsible for notices and a lawful basis for their own use. Use on work devices would be off by default and need local legal steps before activation. Watching people without a lawful basis is not permitted.

## Common questions

### Can I use Pulse today?

No. Pulse is in development. You can ask about early access: see [Contact](https://noxtica.com/contact/).

### Would Pulse run without the device owner knowing?

No. The design goals include a visible indicator, a notice before collection and a view of what is sent. A hidden mode is not planned.

### Is Pulse meant for watching people at work?

No. The planned purpose is integrity and performance signals about a tenant's own application. For work devices, see [Limits](https://noxtica.com/docs/pulse/overview/#limits).

## Related

- [Pulse in Backoffice: applications, profiles, bundles and rollouts](https://noxtica.com/docs/pulse/backoffice/) to configure and publish.
- [Pulse detections, response, devices and privacy](https://noxtica.com/docs/pulse/detections-and-privacy/) for review, appeals, devices and the privacy page.
- [APM and the ingestion service (OTLP)](https://noxtica.com/docs/observability/apm-and-ingest/) for the separate backend telemetry lanes.
- [Authentication](https://noxtica.com/docs/api/authentication/) and [Webhooks](https://noxtica.com/docs/api/webhooks/) for the server API and events.
- [Roles and permissions](https://noxtica.com/docs/security/roles-and-permissions/) for the capabilities above.

---

Source: https://noxtica.com/docs/pulse/backoffice/
Markdown: https://noxtica.com/docs/pulse/backoffice/index.md
Last updated: 2026-10-27

# Pulse in Backoffice: applications, profiles, bundles and rollouts

This page walks an administrator through the Pulse configuration pages in Backoffice, in the order you use them: register an application, author a profile, publish it as a signed bundle and follow the rollout. Read [Noxtica Pulse: endpoint telemetry overview](https://noxtica.com/docs/pulse/overview/) first.

You need the administrator role for every change. Viewers can read all of these pages.

## What it is

Availability: In development.

The pages are under Backoffice → Noxtica Pulse: Pulse, Applications, Profiles, Bundles and Rollouts. They configure what the Pulse desktop client collects for one of your applications and how a change reaches devices. This page does not cover installing the client.

| Page | What it holds |
| --- | --- |
| Applications | The programs Pulse observes. The slug is the join link every device enrols with. |
| Profiles | A draft per application: telemetry, privacy and retention, delivery, and a read-only list of detection rules |
| Bundles | Every signed configuration published for an application. Append-only. |
| Rollouts | The ring-by-ring spread of each published revision, with a health gate |

Reads need the viewer role (`view.pulse`). Writes need the administrator role (`manage.pulse`) and a fresh step-up MFA confirmation, and are recorded in the audit log.

## Prerequisites

- Pulse provisioned for your organisation. Otherwise you see "Pulse is not enabled for this tenant".
- Administrator role and a device for step-up MFA.
- For each operating system you target: the signature details of your program (certificate subject or thumbprint, Apple team ID, ELF build ID or package name). An executable name alone is easy to spoof, so Pulse attaches only to a program whose signature, team or build ID you name.
- A decision, inside your organisation, about which data classes the application may collect and which are optional for the end user.

## Steps

### 1. Register an application

Backoffice → Noxtica Pulse → Applications → **Register application**.

| Field | Rule |
| --- | --- |
| Name | Required, at most 128 characters |
| Slug | 2 to 63 lowercase letters, digits or hyphens, starting with a letter or digit. It becomes the join link and cannot be changed later. |
| Deployment kind | Game, Enterprise or Workforce |
| Allowed modules | Observability, Integrity, Detection (EDR), Response |
| Targets | One or more of Windows, macOS, Linux. Each needs a signer: Authenticode (Windows), Apple team, ELF build ID or package. Add executable names, bundle IDs, install path hints or a product name to narrow the match. |

Press **Register**. Use **Edit** to change fields other than the slug. **Archive** keeps published bundles as the audit trail, but devices stop receiving new configuration and new devices can no longer join.

### 2. Create a profile

Backoffice → Noxtica Pulse → Profiles. Choose the application, press **New profile**, and enter a **Profile name**: 1 to 63 lowercase letters, digits, hyphens or underscores, starting with a letter or digit, for example `eu-staging`. The profile starts from a valid default for the application.

### 3. Set telemetry

Open the profile and the **Telemetry** section. Anything you do not select is never collected.

- **Metrics**: application CPU, memory, threads and handles; frame time; GPU memory and utilisation; host CPU, memory, disk and network. Each metric has an interval in seconds. There is also a default interval and an aggregation window.
- **Sampling**.
- **Collect application logs** with a **Minimum log severity**.
- **Collect session start / end events**.
- **Crash reports**: Off, Metadata only or Full report. **Crash symbolication**: No symbolication or Symbolicate on the server.
- **Host context**: None, Coarse (OS family and hardware class) or Extended (detailed hardware and OS build).
- **Network quality probes**: endpoints the client measures latency and loss against, each with a host, a port and a protocol (HTTPS, TCP or UDP). The client currently measures TCP connect time; probes of other protocols are skipped and reported.

### 4. Set privacy and retention

In **Privacy and retention**:

- **Data classes enabled**: application metrics, application process metadata, crash reports, detections, host metrics, integrity signals, logs, loaded-module metadata, network quality and sessions.
- **Optional for the end user (consent required)**: an optional class is accepted only for users who granted it under the required consent version. Only enabled classes can be optional.
- **Required consent version**: raise it to ask every user to consent again.
- **Pseudonymisation**: Linked (a stable pseudonym across sessions) or Pseudonymous (not linked across applications).
- **Retention class**: the days you request for sessions, measurements, diagnostics, and integrity and detections. A blank field leaves the platform default. The platform can enforce a shorter limit, and a request is limited to the plan maximum.

Backoffice marks the default retention periods and plan maximums as provisional. They can change, so do not quote them to your users from this page. See [Pulse detections, response, devices and privacy](https://noxtica.com/docs/pulse/detections-and-privacy/).

### 5. Set delivery

In **Delivery**, set the **Bundle poll interval (seconds)** if you want to change how often the client checks for a new bundle. An empty value uses the client default. Each device waits that interval plus or minus half of it, so a change reaches every device within one interval after publishing. The setting needs Pulse client 0.3.0 or newer, and publishing raises the minimum client version, so older clients reject the whole bundle.

### 6. Validate and save the draft

Press **Validate**. The validator checks the schema, the red-line rules and the cost bound. A profile that is rejected shows the offending paths and the reason, and **Publish…** stays unavailable until the validator accepts it. Press **Save draft**. Publishing always uses the saved version. If someone saved a newer draft first, Backoffice shows "This profile changed while you were editing" and you reload.

The **Detection rules** list in the profile is read-only. Rules and their response actions cannot be edited in this editor yet; saving keeps them unchanged.

### 7. Publish

Press **Publish…**, then:

1. Enter the **Minimum client version** in the form `x.y.z`, for example `0.1.0`. Older clients ignore the bundle.
2. Enter **Valid for (days)**, from 1 to 30. Clients stop trusting the bundle after that.
3. For a revision after the initial one, optionally open **Advanced: ring plan**.
4. Press **Publish** and confirm step-up MFA.

Backoffice signs saved draft version N and publishes it as the next revision. Every enrolled device picks it up on its next configuration pull.

The Bundles page notes when a bundle is signed with a development key. Such bundles are not for production use and must not be trusted.

### 8. Follow the rollout

Backoffice → Noxtica Pulse → Rollouts.

- The initial revision of an application, a rollback, a bundle that carries a kill switch, and a single-stage plan go live for every device at once.
- Any other publish is staged. A ring plan has one to four stages in the order canary, early, broad. Each stage has a share of devices (a whole number from 1 to 100, larger than the stage before) and a soak time in whole minutes. The final stage must reach 100% of devices.
- The rollout advances while the **health gate** stays green. Signals include devices rejecting the bundle, client CPU and memory use, recent unclean exits, dropped-event rate, export failure rate, upload retries, devices that went silent after applying, devices with a degraded sensor and the reviewed false-positive rate of response actions. A check needs a minimum number of reporting devices for a verdict.
- A new publish is refused while another rollout of the application is still Running or Halted.

### 9. Halt, resume or roll back

On a rollout:

- **Halt** freezes it at the current stage. Devices already in the cohort keep the new revision; others stay on the previous one. You may enter a reason.
- **Resume** continues a halted rollout.
- **Roll back** abandons the rollout and publishes the content of the previous revision again as a new, higher revision, signed anew and served to every device at once. Devices never accept a lower revision number, so the old number itself is not restored.
- **Evaluate now** runs a health check at once.

The same rollback exists on the Bundles page, **Roll back**, for any older revision. Every change is recorded in the rollout's audit timeline.

### 10. Read the bundle history

Backoffice → Noxtica Pulse → Bundles lists revisions newest first with Published, Expires, Content hash, Key ID and Signer. **View** opens a revision and its **Changes vs previous**.

## Verify it works

- The new application is listed under Applications with status Active and appears under Current revision per application on the overview once published.
- Validation shows "The profile is valid".
- After publishing, a message says "Published revision N" and Bundles marks that revision Current.
- Rollouts shows the revision, its stage and "Last health check" results. The initial revision shows "live for every device".
- A halted rollout shows "This rollout is halted" with the reason.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| "Use 2–63 lowercase letters, digits or hyphens" | Slug format | Fix the slug. It cannot be changed after registration. |
| "Choose a signer kind for <OS>." | A target has no signer | Pick a signer and fill its value. |
| "The profile is rejected" | Schema, red-line or cost-bound failure | Read the offending paths and reason, change the profile, validate again. |
| **Publish…** is disabled | Validator has not accepted the draft, or there are unsaved changes | Validate and save the draft. |
| "Use the form x.y.z" | Minimum client version malformed | Enter a version such as `0.1.0`. |
| "The rollout of revision N is still Running" | A new publish is refused during an active rollout | Wait for it to complete, or roll it back. |
| "A ring plan has one to four stages", "The last stage must reach 100% of devices" and similar | Ring plan rules | Correct the stages. |
| "Editing and publishing need the administrator role" | Viewer role | Ask an administrator. |
| "The rollout could not be halted" or "could not be resumed" | Temporary fault or state changed | Refresh and retry. |
| The health gate holds the rollout ("The health data could not be read during this check") | Health data could not be read | Nothing advanced or halted; the next check retries. |
| Older clients ignore a new bundle | The minimum client version was raised | Update the client or lower the minimum for the next publish. |

## Related

- [Noxtica Pulse: endpoint telemetry overview](https://noxtica.com/docs/pulse/overview/) for the whole picture.
- [Pulse detections, response, devices and privacy](https://noxtica.com/docs/pulse/detections-and-privacy/) for review, response, devices and the privacy page.
- [Roles and permissions](https://noxtica.com/docs/security/roles-and-permissions/) for the capabilities used here.
- [Audit log and data export](https://noxtica.com/docs/security/audit-log-and-exports/) for the record of publishes and rollbacks.
- [Privacy](https://noxtica.com/privacy/) and [Security](https://noxtica.com/docs/security/) for data handling.

---

Source: https://noxtica.com/docs/pulse/detections-and-privacy/
Markdown: https://noxtica.com/docs/pulse/detections-and-privacy/index.md
Last updated: 2026-10-27

# Pulse detections, response, devices and privacy

This page covers the Backoffice pages you use once devices report: Detections, Response, Devices, Privacy and Usage, plus the server API and webhook events that connect Pulse to your own account system. A detection is an indicator that a person reviews. It is never a verdict.

Administrators and reviewers use it. Read [Noxtica Pulse: endpoint telemetry overview](https://noxtica.com/docs/pulse/overview/) and [Pulse in Backoffice](https://noxtica.com/docs/pulse/backoffice/) first.

## What it is

Availability: In development.

| Page | What it holds | Role |
| --- | --- | --- |
| Detections | Detections, Appeals, Suppressions and the Review policy | Read: viewer. Per-device evidence: analyst. Review and policy changes: administrator. |
| Response | The response profile (ladder) and the audit of response decisions | Read: viewer. Edit and reverse: administrator. |
| Devices | Enrolled devices, attestation and the attestation policy | Read: viewer. Revoke and policy changes: administrator. |
| Privacy | What the server accepts per application, retention, what Pulse never collects, export and deletion requests | Read-only for everyone; change settings in the profile editor |
| Usage | Meters per UTC day | Viewer |

Writes need step-up MFA and are audited. Opening a detection or a response decision shows per-device evidence, needs the analyst role, and every access is recorded.

### Human review is the default

Under the review policy that applies by default, a detection is an indicator only. No adverse action, such as suspending a session or blocking a device, is permitted until a person confirms the detection in Backoffice. Open, under-review, dismissed, overturned and suppressed detections can never ground an adverse action. The decision stays yours as the controller.

You can switch human review off, but only with a recorded policy reference. Do not do so without your own legal sign-off. Backoffice warns that letting automated actions run on unreviewed detections is solely automated decision-making and needs a legal basis, safeguards and a way to contest.

### Evidence tiers

| Tier | Meaning |
| --- | --- |
| Tier 0 · signal only | Only the fact that the rule fired. No evidence fields. |
| Tier 1 · indicators | A small, fixed set of indicator fields, such as a tool class or a module name |
| Tier 2 · case bundle | Attached on the server after a documented review. Rules cannot request it. |

## Prerequisites

- Pulse provisioned for your organisation, and an application with a published profile that contains detection rules. Until a rule fires on an enrolled device, Detections is empty.
- Administrator role to review, set policy, edit the response profile or revoke a device. Analyst role to open per-device evidence.
- For the server API: a server API key with `read:pulse` or `write:pulse`.
- For response: the Response module enabled for your workspace, and acceptance of the response addendum by an administrator.

## Steps

### 1. Review a detection

Backoffice → Noxtica Pulse → Detections → **Detections**. Filter by severity, status, reason code, device reference, device-owner pseudonym, appeal state and dates. Open a row.

The detail page shows what was detected, why it fired, the evidence fields that were stored (allow-listed fields only), the bundle revision, the audit trail and any appeals. Press **Start review**, then **Confirm detection** or **Dismiss detection**. A **Reviewer note** is required to confirm or dismiss and is recorded in the audit trail.

Statuses: Open, Under review, Confirmed by a reviewer, Dismissed, Overturned on appeal, Suppressed.

### 2. Answer appeals

Device owners file appeals from their own Pulse privacy page. On the **Appeals** tab, filter by state (Appeal open, Appeal under review, accepted, rejected, withdrawn) and press **Resolve**.

- **Accept the appeal — overturn the detection** overturns it and creates a suppression, so later detections of the same rule are recorded as suppressed.
- **Reject the appeal — uphold the detection** keeps the detection.

Enter a **Reason for the decision**. It is recorded in the audit trail and shown to the device owner.

### 3. Manage suppressions

On the **Suppressions** tab, **New suppression** covers a known-good tool. Choose the scope: this rule on one device, this rule for one device owner, or this rule everywhere. A rule-wide suppression silences the rule for every device in the workspace, so prefer the device scope. Choose an expiry (30, 90, 180 by default or 365 days, or never) and enter a reason. While a suppression is active, a matching detection raises no webhook and can never ground an adverse action. **Revoke** ends it.

### 4. Set the review policy

On the **Review policy** tab (**Human review policy**):

- **Require human review before any adverse action** is on by default. To switch it off, enter a **Policy reference** (the document or ticket that approved it, with a minimum length Backoffice states) and confirm.
- **Device owners can appeal detections** turns appeals on or off.
- **Appeal window (days)** is how long a device owner can appeal after a detection. Backoffice shows the allowed range.

### 5. Configure the response ladder

Backoffice → Noxtica Pulse → Response → **Response profile**. A response is what an enrolled device does when a rule fires. Pulse itself never ends a session, stops a process or touches the device.

| Action | Meaning |
| --- | --- |
| Notify the person | Shows a plain-language notice in the desktop app, with a link to contest it |
| Hint: end the session | Tells your application that the session may be ended. What your application does is your decision, and an adverse one needs a person. |
| Observe only | No local action; records that a step matched |
| Report | No local action; the detection is the report |

1. Press **Add a response section**. It starts switched off, in observe mode, with an empty ladder.
2. Add steps. A step selects on exactly one of a rule, a reason code or a severity, and names its actions. Steps are tried top to bottom and the earliest match decides. Set a cooldown in seconds (0 to 604800).
3. Turn on **Requires a person** on every step that can end a session while human review is required. The device then reports the step as held until a person confirms.
4. Choose a **Notice text** from the desktop app's catalogue. Free text is not possible.
5. Set the rate limits and the **Hint lifetime (seconds)**, from 60 to 86400.
6. Choose the **Mode**: Observe (dry run) or Enforce.

Enforce stays unavailable until the **Publish gate** has no blocker: the Response module is enabled, the response addendum is accepted, an observe period has run for its minimum length, at least 30 detections have been reviewed, the measured false-positive rate is at or below your threshold (at most 5%), and the kill switch is off. The platform records the observe period and the measured rate when you publish. A response section needs a minimum client version of 0.2.0 or higher.

Accept the **Response addendum** with **Review and accept**; you can withdraw it at any time, and new hints then stop at once. The **Response kill switch** stops every local response action on devices that take the published bundle, after you save and publish.

On the **Decisions** tab, each decision shows its outcome: Executed, Dry run, or Suppressed (cooldown, kill switch, rate limit) or Held (needs a person). **Reverse this hint…** ends an active hint, requires a reason and delivers the reversal by webhook. Accepting an appeal reverses an active hint automatically.

### 6. Manage devices and attestation

Backoffice → Noxtica Pulse → Devices lists enrolled devices with OS and architecture, client version, key protection (Hardware key, OS key store or Software key), attestation level, "clone suspected", account link and last seen. Accounts, e-mail addresses and global device identifiers are never shown.

The key fingerprint is a one-way identifier of the device key that is specific to your organisation, so the same machine shows a different value in every tenant. Its first 16 of 43 characters are shown; copy the full value with the copy button. A device user can compare it with the value printed by `pulse-ctl device` on the machine.

**Revoke** stops a device being accepted right away; it must enrol again to resume. This cannot be undone. It frees the device's seat.

Attestation levels:

| Level | Meaning |
| --- | --- |
| L0 | Software key. Nothing about the platform is verified. |
| L1 | The device reports an OS key store or hardware key, but the server could not verify platform evidence. |
| L2 | Hardware-backed key. The server verified the platform-reported key attributes. This is not a TPM quote. |
| L3 | A fresh TPM quote of PCR 0 and PCR 7 matched an allowed PCR set of your attestation policy, the device key was certified by the same TPM, and the posture met the policy. The genuineness of the TPM is not verified. |

Attestation is opt-in per application. In **Attestation policy**, press **Enable attestation**, add allowed PCR sets (up to 16, each a sha256 value for PCR 0 and PCR 7 read on a machine you trust), set the posture requirements (Secure Boot, kernel lockdown, IMA, dm-verity) and the maximum age of a statement, then **Save policy**. **Use strict template** requires Secure Boot and kernel lockdown at least integrity. In the current build, TPM statements are collected on Linux only.

### 7. Read the privacy page

Backoffice → Noxtica Pulse → Privacy shows, per application, what the server accepts under its current revision: data classes, which are always collected, which are optional for the player, the required consent version, pseudonymisation and the kill-switch state. A retention table shows your requested days, the applied days and the plan maximum per kind of data. Backoffice marks the default retention periods as provisional.

Change these settings in the profile editor and publish a new revision. The page lists what Pulse never collects, which the client discards before queueing, the server rejects in a configuration and ingest strips. Among them: microphone, camera or any audio or video; browser history, URLs and cookies; the clipboard; credentials or tokens of any kind; file contents; keystrokes and input streams; screen or window contents and window titles; e-mail addresses, contacts and user identity; and environment variable values. No profile setting switches these on.

Players export their data and delete their Pulse account themselves in the Pulse privacy centre; you do not have to run either. Per Backoffice, a deletion cuts the player's devices off at once, erases their detections, appeals and suppressions, deletes their telemetry from the warehouse and records a certificate. For how Noxtica handles data, see [Privacy](https://noxtica.com/privacy/), the [Data Processing Addendum](https://noxtica.com/dpa/) and [Sub-processors](https://noxtica.com/subprocessors/).

### 8. Check usage

Backoffice → Noxtica Pulse → Usage shows, for a month and per UTC day, the counters the ingestion service accepted: enrolled devices, active devices per day, events, metric data points, log volume, crash reports and detections.

### 9. Link players to your accounts with the server API (optional)

Calls go to `https://pulse.noxtica.com` with `Authorization: Bearer sk_prod_your_server_key`. The key needs `read:pulse` or `write:pulse`; create it in Backoffice → Integrations & API → API & SDK. These routes are separate from the `/v1` API. Limits: 300 requests per minute per IP and 120 per key.

| Method and path | Scope | Purpose |
| --- | --- | --- |
| `POST /pulse/v1/tenant/link-codes` | `write:pulse` | Issue a one-time link code for one of your users |
| `GET /pulse/v1/tenant/subjects/{subject}` | `read:pulse` | Status of one player: enrolled or not, attestation level, last seen, open detections |
| `GET /pulse/v1/tenant/links/{subject}` | `read:pulse` | Read one link |
| `DELETE /pulse/v1/tenant/links/{subject}` | `write:pulse` | Unlink |
| `GET /pulse/v1/tenant/decisions` and `/decisions/{id}` | `read:pulse` | Read response decisions |
| `POST /pulse/v1/tenant/decisions/{id}/reverse` | `write:pulse` | Reverse an active hint |

```bash
curl -sS -X POST https://pulse.noxtica.com/pulse/v1/tenant/link-codes \
  -H "Authorization: Bearer sk_prod_your_server_key" \
  -H "Content-Type: application/json" \
  -d '{"externalUserId":"cust_example","appId":"<application-id>"}'
```

The response carries a `url` to hand to that person. The code is valid for 10 minutes, single use, and shown once. At most 5 unused codes exist per application and user, and 30 codes per key per minute. The person opens the address signed in to their Pulse account, sees what your organisation will see and approves or denies. The link is the consent record. A subject can be a pseudonym (`psub_…`), a link subject (`plnk_…`) or your own user id; the answer carries no account e-mail or device identifier. See [Authentication](https://noxtica.com/docs/api/authentication/) and [Errors](https://noxtica.com/docs/api/errors/).

Webhook events you can subscribe to, per endpoint: `pulse.detection.v1`, `pulse.enrolment.linked.v1` and `pulse.response.v1`. Delivery is at least once, so deduplicate by `deliveryId`. See [Webhooks](https://noxtica.com/docs/api/webhooks/).

## Verify it works

- A detection opened by an analyst shows "Evidence (allow-listed fields only)" and an audit trail entry for your access.
- After **Confirm detection**, its status is "Confirmed by a reviewer" and the gate reads "Permitted: a reviewer confirmed this detection."
- After you accept an appeal, the status is "Overturned on appeal" and a suppression appears on the Suppressions tab.
- The Response publish gate shows "Enforce is available" only when no blocker remains.
- A revoked device shows status Revoked and its seat is free.
- A link-code request returns `201` with a `url`.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| "No detections" | No rule has fired on an enrolled device yet | Publish a profile with rules and wait for devices to report. |
| "Reviewing, confirming and dismissing detections needs the administrator role." | Role | Ask an administrator. |
| "Enter the reason for your decision." | A note is required | Fill the reviewer note. |
| "Enter the approved policy reference" when switching review off | Reference too short | Enter the approved document or ticket reference. |
| "Enforce is blocked" with a list of blockers | Addendum, entitlement, observe period, reviewed sample or false-positive rate | Work through each blocker shown under "Why enforce is blocked". |
| "The response addendum text … has not been approved yet" | The addendum text is not available to accept | Ask your account team. |
| "This step can end a session. While human review is required … switch on Requires a person" | Article 22 safeguard | Turn on **Requires a person** for that step. |
| "This hint is no longer active" | It expired or was reversed | Reload to see its current state. |
| Attestation stays below L3 | No policy, PCR values not in the policy, a stale statement, no TPM, or an unsupported platform | Open attestation details for the reason code and fix the policy or the device. |
| Server API `401 missing_api_key` or `invalid_api_key` | Key missing, unknown, revoked or wrong environment | Send a valid server API key. |
| Server API `403 insufficient_scope` or `tenant_not_armed` | Key lacks the scope, or the workspace is not armed | Create a key with the scope; ask your account team. |
| `404 subject_not_found` | Unknown subject, or an unlinked link | Check the identifier and link state. |
| `409 ambiguous_subject` | One user id is linked in several applications | Add `?appId=`. |
| `409 external_user_already_linked` | That user already has an active link in the application | Unlink it first. |
| `429 too_many_outstanding_codes` or `rate_limited` | Too many unused codes or requests | Wait; use a code that is already issued. |

## Related

- [Noxtica Pulse: endpoint telemetry overview](https://noxtica.com/docs/pulse/overview/) for the whole picture.
- [Pulse in Backoffice: applications, profiles, bundles and rollouts](https://noxtica.com/docs/pulse/backoffice/) for publishing configuration.
- [Webhooks](https://noxtica.com/docs/api/webhooks/) and [Authentication](https://noxtica.com/docs/api/authentication/) for events and keys.
- [Roles and permissions](https://noxtica.com/docs/security/roles-and-permissions/) for the capabilities named here.
- [Privacy](https://noxtica.com/privacy/), [Cookies](https://noxtica.com/cookies/) and [Security](https://noxtica.com/docs/security/) for data handling.

---

Source: https://noxtica.com/docs/data-stores-and-connectors/
Markdown: https://noxtica.com/docs/data-stores-and-connectors/index.md
Last updated: 2026-10-28

# Data stores and connectors

The Connectors page in Backoffice lets a workspace administrator choose, for the analytics warehouse, between a **Noxtica-managed (shared platform warehouse)** and **Your own warehouse / provider credentials**. This page explains what each choice means, what you see for each, how to tell which one is active, how to switch, and what Noxtica records.

Availability: depends on your plan, role and the modules enabled for your organisation.

## What a store is

On the Connectors page, a store is a family of connectors that serve one purpose, for example the warehouse that holds your analytics data. Most families have one source: your own account with the service. The warehouse family also has a service that Noxtica operates, so for it you choose which one backs your workspace.

| Family | What you connect | Noxtica-managed option |
| --- | --- | --- |
| Log providers | Sentry, Datadog, AWS CloudWatch, Google Cloud Monitoring, Elastic, Bugsnag, Rollbar or Sumo Logic, through an inbound webhook | No. Always your own account. |
| Issue trackers | Jira or GitHub | No. Always your own account. |
| Messaging | Zendesk, the help desk | No. Always your own account. |
| Warehouse export | ClickHouse, Elasticsearch, BigQuery or an object-storage bucket | Yes. This is the one family with a choice. |

A family without a managed option says so on the page: "Uses your own account — Noxtica has no shared service for this."

A store that has a managed option is always in one of two modes.

| Mode | Meaning |
| --- | --- |
| Noxtica-managed | Your analytics data lives in the shared warehouse that Noxtica operates. There is nothing to set up and no credentials for you to manage. This is the default. |
| Your own | At least one of your own warehouse connectors is enabled. |

The card marked **Active** is the one in effect. Noxtica works the mode out from your own connectors: when none of your own warehouse connectors is enabled, the Noxtica-managed warehouse is active.

## The Noxtica-managed warehouse

### What it is

The Noxtica-managed warehouse is the shared platform warehouse that Noxtica operates for analytics data. It is the default for every workspace. You do not create it or connect it.

### What you see

The Noxtica-managed card on Backoffice → Integrations & API → Connectors shows three facts and a link to this page.

| Field | What it shows |
| --- | --- |
| Region | The region class: European Union, United States or Türkiye. When no class applies it reads "Set by your workspace region". |
| Retention | Your workspace's own retention in days, followed by its class in brackets. Short means up to thirty days, standard means up to four hundred days, and extended means longer than that. When no figure is available the card reads "set by your data policy". |
| Credentials | "Managed by Noxtica". |

The card gives a class, not infrastructure details. It does not list the warehouse's location, provider, names or addresses. What the card shows is what is configured for your workspace. It is not a residency commitment: your contract and the [DPA](https://noxtica.com/dpa/) are the source for commitments.

To read region and retention elsewhere in Backoffice, open Privacy & Legal → Data Locations. It is a read-only table of where each service stores your workspace's data, and it includes a Warehouse analytics row. Your workspace data policy is under Privacy & Legal → Data Retention. See [Data retention, raw IP storage and data locations](https://noxtica.com/docs/compliance/retention-and-locations/).

### What you do not manage

With the Noxtica-managed warehouse you do not create a connection, hold or rotate a key, or keep a credential safe. There is no connector for you to configure, so there is nothing to disable or remove. Noxtica holds the credentials of this service.

A connector type can be in use by the Noxtica-managed warehouse on your workspace. Its card then shows "Managed by Noxtica" and "Used by the Noxtica-managed warehouse on your workspace.", and it has no **Connect** button. Connect one of the other types instead.

## Your own warehouse and provider credentials

### What it is

For the warehouse family you can connect your own ClickHouse, Elasticsearch, BigQuery or object-storage bucket with credentials from your own account. Each kind holds one connection per workspace. The other three families always work this way: you connect your own account, and Noxtica uses the credentials you give it.

### How your credentials are handled

- Credentials are stored encrypted. After you save one, Backoffice never shows it again. The connector shows only whether a credential is set, either "Credential set" or "No credential set".
- When you edit a connector, leave the credential field blank to keep the current value, or enter a new one to replace it.
- A log provider connector gives you a webhook URL that includes a secret token. Backoffice shows it once, when the connector is created.
- A saved connection stays until you remove it. Removing a connector cannot be undone.

The collector's routine mirroring of workspace data to tenant connectors is retired. This page therefore does not describe a routine export of your analytics data into your own warehouse, and nothing here should be read as one.

### Who can change it

Workspace administrators manage connectors. The server checks the permission to manage settings on every read and every change, and every change asks for a fresh step-up multi-factor check. See [Roles and permissions](https://noxtica.com/docs/security/roles-and-permissions/).

## Which one is active, and how to switch

### Tell which one is active

Open Backoffice → Integrations & API → Connectors and look at the warehouse family. It shows two cards: **Noxtica-managed (shared platform warehouse)** and **Your own warehouse / provider credentials**. The card with the **Active** badge is the one in effect. The own card also says how many connections you have saved and how many are in use.

Selecting a card is not the same as making it active. The selection only decides what the page shows next. The badge follows your connectors, so it moves only when a connector is enabled or disabled.

### Switch to your own warehouse

1. Open Backoffice → Integrations & API → Connectors.
2. In the warehouse family, choose **Your own warehouse / provider credentials**. The page shows the connector cards. Nothing changes yet: the page says the Noxtica-managed warehouse stays active until you connect and enable a connector.
3. Connect a warehouse connector with credentials from your own account, and complete the multi-factor check when asked. A new connector is enabled when you save it.
4. Confirm that the **Active** badge is now on the own card.

If you saved exactly one own connection earlier and none is in use, the own card offers **Use my saved connection**. It enables that connection again after the same multi-factor check.

### Switch back to the Noxtica-managed warehouse

1. While your own warehouse is active, choose the **Noxtica-managed (shared platform warehouse)** card.
2. Read the confirmation, "Use the Noxtica-managed warehouse?". It says your own warehouse connections stop being used, and that their saved details are kept so you can switch back at any time.
3. Select **Switch to Noxtica-managed** and complete the multi-factor check.
4. Confirm that the **Active** badge is back on the Noxtica-managed card.

Switching back disables your own warehouse connectors and keeps their saved details. Nothing is deleted. While the Noxtica-managed warehouse is active, the card notes that your saved connections are kept but not in use. To switch again, choose the own card, then use **Use my saved connection** or enable the connector you want. To delete a saved connection, remove the connector itself.

Because the mode follows your connectors, disabling or removing the last enabled warehouse connector also returns the workspace to the Noxtica-managed warehouse.

## What is recorded

Every change is recorded in the audit log under Backoffice → Administration → Audit Log.

| Entry | When it is written |
| --- | --- |
| `integration_created` | You connect a connector. It records the connector kind and its name, and whether a credential was set. |
| `integration_updated` | You change a connector, including enabling or disabling it. |
| `integration_deleted` | You remove a connector. |
| `connector_store_mode_changed` | The active warehouse changes between Noxtica-managed and your own. It records the store, the previous mode, the new mode and what caused the change. |

A mode entry is written only when the active warehouse really changes. A connector change that leaves it as it was still writes its own connector entry. No entry contains a credential or its encrypted form. How long entries are kept depends on your plan. See [Audit log and data export](https://noxtica.com/docs/security/audit-log-and-exports/).

## Related

- [Integrations and API pages](https://noxtica.com/docs/backoffice/integrations/): where Connectors sits among the other Integrations & API pages.
- [Data retention, raw IP storage and data locations](https://noxtica.com/docs/compliance/retention-and-locations/): the data policy, and the read-only table of data locations.
- [Audit log and data export](https://noxtica.com/docs/security/audit-log-and-exports/): read, filter and export the entries described above.
- [Roles and permissions](https://noxtica.com/docs/security/roles-and-permissions/): who can manage connectors and which changes need a step-up check.
- [DPA](https://noxtica.com/dpa/) and [Subprocessors](https://noxtica.com/subprocessors/): the public legal documents.

---

Source: https://noxtica.com/docs/observability/overview/
Markdown: https://noxtica.com/docs/observability/overview/index.md
Last updated: 2026-10-27

# Observability overview: RUM, replay, APM and ingest

Noxtica observability shows what happens in your visitors' browsers: performance, errors, console output, recorded sessions and behavior. Separate ingestion keys cover your own backend. This page maps each tool to what it measures, the Backoffice page that shows it, what you install and the gates it passes. The rest of the section has one page per tool.

## What it is

Availability: session replay and real user monitoring have Controlled availability. APM has In development. The other tools on this page have no separate label: availability depends on your plan, role and the modules enabled for your organisation. Every tool runs when enabled for your organisation and is off for a domain until you switch it on.

### The browser tools

| Tool | What it measures | Read it in Backoffice | Switch it on in Backoffice | Guide |
| --- | --- | --- | --- | --- |
| Real user monitoring | Web Vitals, navigation timings, page views, error counts, SDK health | Session Insights → RUM & APM → **Client RUM** | Web Analytics & Privacy → **Consent & Privacy** and **RUM Collection**, then a per-domain sample rate | [RUM](https://noxtica.com/docs/observability/rum/) |
| Error detail | Redacted error occurrences, grouped, with stack frames | Session Insights → **Issues** → Errors | Web Analytics & Privacy → **Tracking Allowlists** → **RUM trace controls** | [Errors](https://noxtica.com/docs/observability/errors-and-source-maps/) |
| Console logs | Masked browser console lines | Client RUM → **Console logs** | Web Analytics & Privacy → **Capture Policies** | [Errors](https://noxtica.com/docs/observability/errors-and-source-maps/) |
| Source maps | Original file, line and name for a stack frame | Issues → stack trace | An upload from your build | [Errors](https://noxtica.com/docs/observability/errors-and-source-maps/) |
| Session replay | Masked recordings you can play back, and Live Assist | Session Insights → **Session Replay** | Privacy & Legal → **Legal Basis Register**, Web Analytics & Privacy → **Capture Policies** | [Replay](https://noxtica.com/docs/observability/session-replay/) |
| Behavior analytics | Clicks, scroll depth, page-to-page paths, conversion steps | Session Insights → **Behavior Analytics**, **Heatmaps**, **Journeys**, **Funnels** | Administration → **Domains** → Configuration → **Tracker policy** | [Behavior](https://noxtica.com/docs/observability/behavior-analytics/) |
| Events, tags and tracing | App events, session tags, hashed identity, trace headers | Behavior Analytics, replay timeline | Web Analytics & Privacy → **Tracking Allowlists** | [Events](https://noxtica.com/docs/observability/events-and-tracing/) |

Heatmaps, journeys and funnels sit under Behavior Analytics in the sidebar. The page called Behavior Analytics is the runtime tracker.

### How data flows

1. The core script loads on the page and gets a short-lived token and the domain's signed policy from the collector host. Clients refresh the token about every 5 minutes, so a policy change can take a few minutes to reach visitors.
2. The extensions script starts the lanes that the policy and the visitor's consent allow.
3. Each lane sends to the ingest host. The collector checks consent, Do Not Track, Global Privacy Control and the domain policy again on its side, and it discards what the checks refuse.
4. Backoffice reads the stored data under the signed-in user's role and tenant scope.

### What you install in the browser

| Piece | Needed for | Notes |
| --- | --- | --- |
| Core script | Everything | Loads the extensions. On its own it never sends RUM, replay or tracker data. |
| Extensions script | RUM, error detail, console logs, replay, tracker, heatmaps, journeys | Load it after consent, or switch on Auto-load extensions in Script & Consent. |
| Recorder head | Replay from the start of the page | Optional. A small synchronous script that must run before every other script in `<head>`. |
| Content Security Policy | All of the above | Allow the collector host `collect.noxtica.com` and the ingest host `ingest.noxtica.com` in `connect-src`, and `'wasm-unsafe-eval'` in `script-src`. |

Telemetry goes to the ingest host and fails over to the collector once, then stays there. A policy that allows one of the two hosts and not the other breaks part of the traffic. See [Install & Browser Runtime](https://noxtica.com/docs/browser-runtime/) and [Content Security Policy, hosts and relay](https://noxtica.com/docs/sdk/csp-and-relay/).

Backend traces, metrics and logs use separate ingestion keys and are not covered by the site key. See [APM and the ingestion service (OTLP)](https://noxtica.com/docs/observability/apm-and-ingest/).

### Consent and legal-basis gates

| Tool | Visitor consent category | Record in Backoffice | Do Not Track and Global Privacy Control |
| --- | --- | --- | --- |
| RUM, error detail, console logs | `analytics` | A per-domain privacy decision in **Consent & Privacy** | Honor, or a documented override with a legal basis |
| Session replay | `replay` | A replay legal basis in the **Legal Basis Register**, plus the replay policy | Honor, or a documented override |
| Behavior analytics and app events | `analytics` | The domain's tracker switches | Honor when the domain policy is Honor |
| Live Assist | Its own consent, asked of the visitor | A replay policy, and the feature enabled for your organisation | See the replay guide |

The consent categories apply in consent-gated modes (`api` and `cookie`). See [Consent modes, GPC and Google Consent Mode](https://noxtica.com/docs/sdk/consent/). Legal text is on the [Privacy](https://noxtica.com/privacy/) and [Cookies](https://noxtica.com/cookies/) pages. The decisions you record are your organisation's own: Noxtica does not make them for you.

## Prerequisites

- **Roles.** Reading Client RUM, Issues and Behavior Analytics needs the Viewer role or higher. Listing replay sessions needs the Analyst role. Switching tools on, and the capture policies, need the Admin role and a fresh step-up verification. Replay playback needs a separate replay-payload permission.
- **Browser.** The core script is installed and the page allows the hosts above.
- **Privacy owner.** Someone who can record a legal basis for your organisation. For replay this is a tenant administrator.
- **Flags.** Each tool runs when enabled for your organisation. Where a switch is a Noxtica operator action, the tool's page says so.

## Steps

### 1. Install the browser pieces

Backoffice → Integrations & API → **Script & Consent** → **Snippets** prints the tags with your site key and hosts filled in. Add the recorder head if you use replay. Load the extensions after consent, or switch on **Load the extensions script automatically** for the domain.

### 2. Decide consent and legal basis

Write down, per domain, which categories your banner grants for each tool, and who records the legal basis. Use the table above. Start with the tightest settings you can live with: strict masking, a low sample rate, and capture off for tools you do not need.

### 3. Switch each tool on

Follow the guide for the tool in the browser tools table. Each guide lists the exact Backoffice path, the roles it needs and the limits it enforces.

### 4. Confirm data arrives

Open the page named in the browser tools table. Client RUM, Session Replay, Heatmaps and Funnels name the missing switch when they are empty, so the empty state is the quickest diagnosis.

### 5. Review retention, usage and deletion

- Backoffice → Web Analytics & Privacy → **RUM Data Lifecycle** lists what each lane stores and its retention. It offers a permanent purge for console logs, error details and replay. Base RUM counters are platform-managed and have no purge control.
- Replay retention is set in the replay policy. Error-detail retention is set in RUM Data Lifecycle. Both accept 1 to 90 days and start at 7 days on every package. Error details, console log lines and APM data are held in the analytics warehouse, which removes them after 7 days, so a longer setting does not keep them longer.
- Backoffice → Billing & Plan → **Usage & Quotas** shows metered usage. See [Usage, quotas and metering](https://noxtica.com/docs/billing/usage-and-quotas/).
- For requests about a person, see [Data subject scope, erasure requests and account deletion](https://noxtica.com/docs/compliance/requests-and-deletion/).

## Verify it works

| Tool | What you see when it works |
| --- | --- |
| RUM | Client RUM shows Total samples and an LCP value for the domain |
| Error detail | Issues → Errors lists a group after a test error |
| Console logs | Client RUM → Console logs lists masked lines |
| Replay | Session Replay → **Install & status** shows **Armed**, and **Sessions** lists a playable session |
| Behavior analytics | Behavior Analytics shows non-zero Total events and a session count |
| Tracing | A request to an allow-listed origin carries a `traceparent` header |

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| Every page is empty | The extensions script does not load, consent is not granted, or the Content Security Policy blocks the ingest host. | Check the install, the consent state and `connect-src`. |
| **Client RUM capture is off** or **No domain is sampling RUM** | The workspace switch is off, or every domain sample rate is 0. | See [RUM](https://noxtica.com/docs/observability/rum/). |
| **Session replay has never been armed** or **Recording is off for every domain** | No active replay legal basis, or no enabled policy. | See [Replay](https://noxtica.com/docs/observability/session-replay/). |
| **Heatmap collection is off** | Tracker, Browser interactions or Heatmaps is off for the domain. | See [Behavior](https://noxtica.com/docs/observability/behavior-analytics/). |
| **No runtime errors** | Error detail is off, or a gate is closed. | See [Errors](https://noxtica.com/docs/observability/errors-and-source-maps/). |
| An event or tag is missing | Its name or key is not on the allow-list. | See [Events](https://noxtica.com/docs/observability/events-and-tracing/). |
| A switch is not editable for your role | The control is an operator action or needs the Admin role. | Ask your account team or an administrator. |

## Related

- [Real user monitoring and Web Vitals](https://noxtica.com/docs/observability/rum/) — Web Vitals, sample rate and the Client RUM page.
- [Browser errors, console logs and source maps](https://noxtica.com/docs/observability/errors-and-source-maps/) — error capture and symbolication.
- [Session replay: setup, masking and playback](https://noxtica.com/docs/observability/session-replay/) — legal basis, masking and playback.
- [Custom events, session tags and request tracing](https://noxtica.com/docs/observability/events-and-tracing/) — events, tags, identity and trace headers.
- [Behavior analytics: heatmaps, journeys and funnels](https://noxtica.com/docs/observability/behavior-analytics/) — the tracker and its views.
- [APM and the ingestion service (OTLP)](https://noxtica.com/docs/observability/apm-and-ingest/) — backend telemetry.
- [Uptime checks, alerts, status reports and the status page](https://noxtica.com/docs/observability/uptime-alerts-status/) — alerts on the metrics above.
- [Browser SDK troubleshooting](https://noxtica.com/docs/sdk/troubleshooting/) — script and consent problems.

---

Source: https://noxtica.com/docs/observability/rum/
Markdown: https://noxtica.com/docs/observability/rum/index.md
Last updated: 2026-10-27

# Real user monitoring and Web Vitals

Real user monitoring (RUM) measures how your pages perform for real visitors. A tenant administrator turns it on and records the privacy decision, a web developer makes sure the extensions script loads, and anyone with analytics access reads the results on the Client RUM page.

## What it is

Availability: Controlled availability. RUM is off until it is switched on for your workspace and for a domain, and it runs when enabled for your organisation.

The browser sends small, sampled beacons to the ingest host. The beacons come from the extensions script. The core script alone never sends RUM.

| Group | What you see | Backoffice name |
| --- | --- | --- |
| Web Vitals | Loading speed, visual stability, responsiveness and paint timing | LCP, CLS, INP, FCP |
| Navigation timings | DNS lookup, TCP connect, TLS handshake, response start and DOM processing | DNS lookup, TCP connect, TLS handshake, TTFB, DOM processing |
| Page views | Sampled page views, including route changes in single-page apps | Pageviews |
| Error counts | Uncaught errors and unhandled promise rejections, recorded under a closed set of names. Raw error message text is not used as a name. | Capped error count, Error rate |
| API latency | Mean round trip of the SDK's own calls to Noxtica's `/client/*` endpoints. It is never your page's own requests. | API latency |
| Resource timing | Durations for third-party hosts you allow-list | Resource duration |
| SDK health | The SDK and recorder's own counters and closed diagnostic codes, never page content | SDK health panel |

Each Web Vital is rated Good, Needs improvement or Poor against the standard Core Web Vitals boundaries. For what the browser stores on the visitor's device and which category governs it, see [Install & Browser Runtime](https://noxtica.com/docs/browser-runtime/) and [Privacy](https://noxtica.com/privacy/).

### Gates

Beacons flow for a domain when all of these hold:

1. **Workspace switch.** RUM Collection is on for the workspace. It is off by default.
2. **Domain sample rate.** The domain's Client RUM sample rate is above 0. A rate of 0 means nothing is sent. The default is 0.
3. **Privacy decision.** The domain records whether visitors must consent, a legal basis if they do not, and how Do Not Track and Global Privacy Control are handled.
4. **Visitor signals.** With the policy set to Honor, a visitor who sends Do Not Track or Global Privacy Control is excluded. The browser checks it and the collector checks it again. In consent-gated modes (`api` and `cookie`), the `analytics` category must also be granted.

Because sampling decides which page views send beacons, treat the numbers as a sample, not a census.

## Prerequisites

- **Extensions script.** It must load on the page, either through your consent flow or through Auto-load extensions. See [Consent modes, GPC and Google Consent Mode](https://noxtica.com/docs/sdk/consent/).
- **Roles.** Switching on RUM Collection and recording the privacy decision need the Admin role and a fresh step-up verification. Reading Client RUM needs the Viewer role or higher.
- **Sample rate.** Today the per-domain sample rate field is editable by Noxtica operators. It is disabled for tenant roles in Backoffice, so ask your account team to set it.
- **Content Security Policy.** The page allows the collector host and the ingest host in `connect-src`. See [Content Security Policy, hosts and relay](https://noxtica.com/docs/sdk/csp-and-relay/).
- **Flags.** RUM works when enabled for your organisation.

## Steps

### 1. Make the extensions script load

Pick one route. Both are on Backoffice → Integrations & API → Script & Consent.

- **Your site loads it after its own consent.** Record the visitor's choice with `setConsent()`, then load the extensions. Visitors who decline never load them and send no RUM.
- **Turn on Auto-load extensions.** Switch on **Load the extensions script automatically** for the domain. No change to your site is needed.

### 2. Record the domain's privacy decision

Backoffice → Web Analytics & Privacy → **Consent & Privacy**. The **Consent & privacy decisions** card puts domains that still need a decision at the top of its list.

1. Choose the **Legal basis**. The list offers `rum_observability`. Leave it at `— none —` when visitors must consent.
2. Set **Requires consent**.
3. Set the **DNT/GPC policy** to **Honor**, or to **Documented override**.
4. Select **Save decision** and complete the step-up verification.

Rules the page enforces:

- Capturing without consent needs an approved legal basis.
- Overriding Do Not Track and Global Privacy Control needs an approved legal basis and your acknowledgement: "I acknowledge this domain overrides DNT/GPC on an approved legal basis."
- This decision covers per-domain RUM consent and Do Not Track decisions. Tenant-wide gate receipts are recorded in the Legal Basis Register.

### 3. Turn on RUM Collection for the workspace

Backoffice → Web Analytics & Privacy → **RUM Collection**. Switch **Client RUM collection** on and select **Save**. The page shows when the setting last changed.

### 4. Set the domain's sample rate

Backoffice → Administration → Domains → open the domain → **Configuration** → **Client RUM** → **Sample rate**. The value runs from 0 (off) to 1 (every page view) and defaults to 0. Raising a rate above 0.5 from a value at or below it needs a separate risk acknowledgement.

Ask your account team to apply the value until your role can edit it.

### 5. Optional: report on third-party resources

Backoffice → Web Analytics & Privacy → **Tracking Allowlists** → **RUM trace controls**.

1. Add hostnames under **Resource-host allowlist**. Use lowercase hostnames without a port or an IP address. The list holds up to 50 hosts.
2. Switch on **Enable Resource-Timing observation**.
3. Select **Save trace controls**.

The observer installs when the switch is on and the list is not empty. For trace origins see [Custom events, session tags and request tracing](https://noxtica.com/docs/observability/events-and-tracing/).

### 6. Read the Client RUM page

Backoffice → Session Insights → RUM & APM → **Client RUM**.

- **Filters.** Choose **Domain**, **Device** (Desktop, Tablet, Mobile, Unknown), **Browser** (Chrome, Firefox, Safari, Unknown) and **Time range**.
- **Overview tab.** KPIs show Total samples, Error rate, LCP, API latency and Capped error count. The metrics table shows each metric's samples, mean and the split across Good, Needs improvement and Poor.
- **Vitals by environment.** INP, LCP and CLS are broken down by connection type, device memory and CPU bucket. Browsers that do not expose connection type or device memory, such as Safari and Firefox, land in the Unknown bucket.
- **SDK health.** The SDK and session recorder's own counters, such as recorder starts, events dropped, flush failures and diagnostics.
- **Errors tab.** It opens the Issues page. See [Browser errors, console logs and source maps](https://noxtica.com/docs/observability/errors-and-source-maps/).
- **Console logs tab.** Masked console lines, when capture is on.

## Verify it works

1. Load a page on the domain, accept consent if your site asks, and browse for a minute.
2. In your browser's network panel, look for requests to the ingest host whose path starts with `/client/rum`.
3. On the Client RUM page, widen **Time range** if needed. **Total samples** rises and LCP shows a value.
4. If a card is empty, read its message. Each message names the missing switch.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| **Client RUM capture is off** | RUM Collection is off for the workspace. | Switch it on in step 3. |
| **No domain is sampling RUM** | The workspace is on but every domain has a sample rate of 0. | Ask your account team to set a rate in step 4. |
| **RUM needs the extensions script, and your settings do not load it** | Auto-load extensions is off and your page does not load the extensions. | Use either route in step 1. |
| **No visitors in this window yet** or **No RUM data in this window** | The window is too short, or no sampled visit arrived. | Widen the range, clear filters, wait for traffic. |
| **No RUM data in this window**, capture settings could not be read | Backoffice could not read the capture settings. | Open **RUM Collection** and check the switch. Retry. |
| Visitors with Do Not Track or Global Privacy Control are missing | The domain policy is Honor. | This is the intended behaviour. Change the policy with a recorded legal basis. |
| Save refused: consent-optional capture needs a basis | You turned off **Requires consent** without a legal basis. | Choose `rum_observability`, or turn **Requires consent** on. |
| Save refused: override needs a basis | You chose **Documented override** without a legal basis. | Choose a legal basis and tick the acknowledgement, or set the policy back to **Honor**. |
| Vitals by environment shows mostly Unknown | The browser does not expose connection type or device memory. | No fix. Safari and Firefox expose neither. |

## Who it fits

Use RUM to see where friction appears, then decide what to change.

- **How do visitors move within a page load?** Where tracker collection is enabled, the console also offers journeys, funnels and heatmaps. A tracker session covers one page load by design, so they do not follow visitors across pages. See [Behavior analytics: heatmaps, journeys and funnels](https://noxtica.com/docs/observability/behavior-analytics/).

## How teams connect

RUM runs from the same browser script as the rest of Noxtica and needs no extra code. You connect it in three places:

- **Your pages.** Use the Noxtica browser collector. See [step 1](https://noxtica.com/docs/observability/rum/#1-make-the-extensions-script-load) and [Install & Browser Runtime](https://noxtica.com/docs/browser-runtime/).
- **The Noxtica console.** Set the sample rate for each domain. It can stay at zero. See [step 4](https://noxtica.com/docs/observability/rum/#4-set-the-domains-sample-rate).
- **Your consent tool.** In consent-gated modes, connect it so the page reports analytics consent. See [Consent modes, GPC and Google Consent Mode](https://noxtica.com/docs/sdk/consent/).

## Limits

Measurements are samples from browsers that allow collection.

- Controlled availability. Capture and read access are configured separately for each tenant and domain, and access is agreed with Noxtica.
- A missing measurement does not mean a good or a bad visit. Browser support, privacy settings and consent change what is collected.
- You are responsible for notice, consent, sampling and retention. Console output and error detail can contain personal data that your page writes.
- Measurements and any alerts built on them can produce false positives and false negatives. Your team decides what to do. Native mobile app monitoring is not supported.

## Common questions

### Is RUM the same as session replay?

No. RUM samples performance and error measurements. Session replay records page structure and interactions and has its own consent category. See [Session replay: setup, masking and playback](https://noxtica.com/docs/observability/session-replay/).

### Can I follow a visitor across pages?

No. Journeys and funnels do not span pages. The reason is in the third item under [Who it fits](https://noxtica.com/docs/observability/rum/#who-it-fits).

### Can I turn RUM off for a domain?

Sampling is set per domain and can stay at zero, which sends nothing. See [step 4](https://noxtica.com/docs/observability/rum/#4-set-the-domains-sample-rate). Capture and read access are configured separately; see [Limits](https://noxtica.com/docs/observability/rum/#limits).

## Related

- [Observability overview: RUM, replay, APM and ingest](https://noxtica.com/docs/observability/overview/) — how RUM fits with the other tools.
- [Browser errors, console logs and source maps](https://noxtica.com/docs/observability/errors-and-source-maps/) — error detail and console capture.
- [Install & Browser Runtime](https://noxtica.com/docs/browser-runtime/) — core and extensions scripts, consent categories, storage.
- [Legal basis register and receipts](https://noxtica.com/docs/compliance/legal-basis/) — tenant-wide receipts.
- [Usage, quotas and metering](https://noxtica.com/docs/billing/usage-and-quotas/) — RUM events and sessions are metered.

---

Source: https://noxtica.com/docs/observability/errors-and-source-maps/
Markdown: https://noxtica.com/docs/observability/errors-and-source-maps/index.md
Last updated: 2026-10-27

# Browser errors, console logs and source maps

This page covers the three ways Noxtica records what goes wrong in a visitor's browser: error counts, redacted error detail and masked console logs. It also shows how to upload source maps so stack traces point at your original code. A tenant administrator sets the switches, a developer tags builds and uploads maps, and analysts read the results.

## What it is

Availability: Controlled availability, as part of real user monitoring. Each capture below has its own switch and is off by default. It runs when enabled for your organisation.

| Layer | What you get | Where you read it |
| --- | --- | --- |
| Error counts | Counts of uncaught errors and unhandled promise rejections, with no message or stack. They are part of [Real user monitoring and Web Vitals](https://noxtica.com/docs/observability/rum/). | Client RUM → Overview |
| Redacted error detail | One row per error occurrence: a redacted message summary and redacted stack-frame paths, with up to 20 frames kept. Raw error text is never stored. Errors are grouped, so the same fault counts once as a group with a number of occurrences. | Session Insights → Issues → Errors |
| Console logs | Masked console output from visitors' browsers at the levels `log`, `info`, `warn`, `error` and `debug`. | Client RUM → Console logs |
| Source maps | Your uploaded maps sit in a private store. The Issues page reads them at view time to show original file, line, column and name beside the raw frame. | Issues → stack trace |

Every capture follows the domain's privacy decision (consent, Do Not Track and Global Privacy Control, legal basis) and the visitor's `analytics` consent in consent-gated modes. Error detail also needs RUM Collection on and a domain sample rate above 0. See [Real user monitoring and Web Vitals](https://noxtica.com/docs/observability/rum/).

Source maps are never returned by any read route. The Issues page returns the resolved frame, not the map. If symbolication fails or is off, you see the raw frame, unchanged.

## Prerequisites

- **Extensions script.** Error detail and console logs come from the extensions script. See [Install & Browser Runtime](https://noxtica.com/docs/browser-runtime/).
- **RUM on.** RUM Collection is on and the domain has a sample rate above 0.
- **Privacy decision.** The domain has a recorded consent and Do Not Track decision.
- **Arming error detail.** Today a Noxtica operator is the sole role that can switch it on for a domain. Anyone who can manage the domain can switch it off again at any time, with no confirmation. Ask your account team to arm it.
- **Console logs.** The Admin role and a fresh step-up verification.
- **Source maps.** The Admin role to mint an upload token, with a fresh step-up verification. The domain's symbolication setting depends on your account: Backoffice has no switch for it today, so ask your account team to turn it on once maps are uploaded.
- **Reading.** The Viewer role or higher reads Issues and Client RUM.

## Steps

### 1. Tag your builds with release and build id

Source maps match errors by build id. Pass `release` (a label) and `buildId` (the immutable id of one deploy, for example a commit SHA) when you create the client yourself, in place of `data-auto-init`:

```js
const client = NoxticaCollector.createClient({
  siteKey: '<your-site-key>',
  release: '2026.10.27',
  buildId: '<commit-sha>',
});
```

- Each value is up to 128 characters from `A-Z a-z 0-9 . _ -`. An off-pattern value is dropped and never sent.
- The auto-initialised single-tag client has no attribute for these values. Without a `buildId`, errors are never symbolicated.
- A bare `release` label is not an artifact identity. Two deploys with the same label are told apart by `buildId`.

### 2. Turn on redacted error detail

Backoffice → Web Analytics & Privacy → **Tracking Allowlists** → **RUM trace controls** → **Redacted error-detail capture**.

1. Pick the domain.
2. Switch on **Capture redacted error detail on this domain**. Whoever switches it on confirms that the organisation records this as controller and that the domain's consent and lawful-basis settings cover it. Today that is a Noxtica operator.
3. Choose **Page URL capture** (below).

If the switch is on but nothing is captured, the card says **On, but not capturing** and names the cause: the workspace RUM switch is off, the sample rate is zero, the consent or Do Not Track policy is incomplete, a Do Not Track override has no recorded legal basis, or the domain neither requires consent nor has a legal basis.

Each domain stores up to 50,000 error occurrences a day. Retention defaults to 7 days and is set in step 7.

| Page URL capture | What is stored with an error or console line |
| --- | --- |
| Full (origin + path + redacted query), the default | The origin, path and a redacted query |
| Path only | Origin and path. The query is dropped. |
| Off | No page URL |

Query parameters that look like credentials or identifiers (`token`, `key`, `secret`, `password`, `auth`, `session`, `sig`, `code`, `otp`, `email`, `phone`) are stripped in every mode.

### 3. Turn on console-log capture

Backoffice → Web Analytics & Privacy → **Capture Policies** → **Browser console-log capture**.

1. Pick the domain.
2. Switch on **Capture browser console logs on this domain**.
3. Set **Sample rate (% of visits)**. The card shows the stored value in ppm, where 1,000,000 ppm is 100%.
4. Select **Save capture policy** and complete the step-up verification.

Messages are masked on the server before they are stored, and raw values are never stored. Limits:

| Limit | Value |
| --- | --- |
| Entries per request | 50 |
| Daily budget per device | 500 entries by default |
| Share of the budget for `log`, `info` and `debug` | 80%, so a later `error` or `warn` is not displaced |

Bounds can change. Backoffice shows the values in force.

### 4. Mint a source-map upload token

An upload token covers one build and one list of files. It lasts 10 minutes. An administrator mints it from a Backoffice session after a fresh step-up verification, because the token grants write access to the private store. Backoffice has no screen for this today, so the call is an API request:

```http
POST https://backoffice.noxtica.com/api/analytics/rum_source_maps/upload-authorizations
Content-Type: application/json

{
  "domainId": "<your-domain-id>",
  "buildId": "<commit-sha>",
  "release": "2026.10.27",
  "manifest": [
    { "filePath": "assets/app.js.map", "byteCount": 482113, "contentSha256": "<64-hex-sha256>" }
  ]
}
```

A response of `201` carries `token` and `expiresAt`. Rules: `buildId` uses `A-Z a-z 0-9 . _ -` up to 128 characters. `release` also allows `/` and runs to 256 characters. The manifest holds 1 to 500 files. `byteCount` is the exact size in bytes, and `contentSha256` is the lowercase SHA-256 of the file.

An unattended CI job cannot pass step-up verification by itself. Run the mint as an approved operator, then hand the short-lived token to the build.

### 5. Upload the maps from your build

Send each file in the manifest once, with the token as a bearer credential. No session is needed.

```bash
curl -X POST \
  "https://backoffice.noxtica.com/api/analytics/rum_source_maps/upload?filePath=assets%2Fapp.js.map" \
  -H "Authorization: Bearer <upload-token>" \
  --data-binary @dist/assets/app.js.map
```

A success returns `{ "ok": true, "status": "active" }`. Repeating an upload returns `already_active`, so a retried build is safe. Do not deploy `.map` files to your public host. Remove them from the deploy output once every file has uploaded.

Limits in force by default:

| Limit | Default |
| --- | --- |
| Size of one map | 10 MiB |
| Maps per release | 100 |
| Active bytes per tenant | 2 GiB |
| Active releases per tenant | 20 |

These values are configuration and can change. A rejected upload names the limit.

### 6. List or delete maps

`GET https://backoffice.noxtica.com/api/analytics/rum_source_maps` lists active maps for the tenant. Add `?build_id=<id>` to filter. It needs the Viewer role. `DELETE .../rum_source_maps/<map-id>` removes one map. It needs the Admin role and a fresh step-up verification.

### 7. Read errors and set retention

Backoffice → Session Insights → **Issues**.

- **Errors tab.** Errors are grouped with counts, affected sessions and users where recorded, and a redacted stack trace. The **Behavior** tab holds rage-click and similar groups. See [Behavior analytics: heatmaps, journeys and funnels](https://noxtica.com/docs/observability/behavior-analytics/).
- **Window.** Choose 1, 7, 14, 30 or 90 days. A window never shows more than the error-detail retention keeps, 7 days by default.
- **Filters.** Search by text, type, route, severity, release, build, platform, browser, operating system and device type. **URL contains** needs at least 2 characters.
- **Severity.** Severity is a deterministic rule on occurrences times affected users, with 1 when users are not recorded: 1,000 or more is Critical, 100 or more High, 10 or more Medium, otherwise Low. Checkout, payment and billing routes have a High floor. No AI grading is involved.
- **New and Ongoing.** New means the group started inside the window, within retained history.
- **Detail.** The drawer has Overview, Stack trace and Context. **Watch replay** opens a linked replay, which exists when the occurrence recorded an exact link to a retained, consented session. **Copy link** copies the address.

Backoffice → Web Analytics & Privacy → **RUM Data Lifecycle** shows what each lane holds and its retention. Set **Retention (days, 1–90)** for error details per domain. The default is 7 days, which is also the platform window: a longer value does not keep error details longer. The page also offers a permanent **Purge** for console logs, error details and replay. A purge cannot be undone.

Backoffice → Session Insights → Client RUM → **Console logs** lists masked lines. Filter by **Level**, **Window**, **Search message** (2 characters or more), **Page URL**, **Device ID** or **Replay session ID**. **Export** downloads CSV, JSON or text after a step-up verification.

## Verify it works

1. Throw a test error on a page of the domain, for example `setTimeout(() => { throw new Error('noxtica-test') })`. Sampling can skip a visit, so repeat it if nothing appears.
2. Open Issues → Errors. The error appears with an occurrence count. If the card is empty, **Review capture settings** opens the switches.
3. After uploading maps for the same `buildId`, open the group. The stack trace shows the original file, line and column beside the raw frame.
4. Call `console.warn('noxtica-console-test')` on the page. The line appears under Client RUM → Console logs. Any masked part of a message shows as `[REDACTED]`.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| **No runtime errors** on Issues | Error detail is off, or a gate of the card **On, but not capturing** is closed. | Check each cause listed on the card in step 2. |
| Errors show raw frames after you uploaded maps | The error has no `buildId`, the `buildId` differs from the upload, or the domain's symbolication setting is off. | Pass `buildId` in step 1, match it in the manifest, and ask your account team about symbolication. |
| Console logs tab is empty | Capture is off, the sample rate is 0, or no entry arrived in the window. | Check step 3 and widen the window. |
| A console message shows `[REDACTED]` | The server masked part of the value before storing it. | None. The original value was never stored. |
| Upload returns `401` `unauthorized` or `expired` | The token is missing, malformed or older than 10 minutes. | Mint a new token. |
| Upload returns `403` `file_not_in_manifest` | The `filePath` does not match a manifest entry exactly. | Use the same string as in the manifest. |
| Upload returns `400` `byte_count_mismatch` or `content_hash_mismatch` | The file differs from what the manifest declared. | Recompute size and SHA-256 from the final file. |
| Upload returns `413` or `409` | A size limit, release limit, tenant byte limit or active-release limit was reached. | Delete old maps or ask your account team. `quota_race` is safe to retry. |
| Upload returns `503` | Map storage is not ready for your account. | Ask your account team. |
| Some console lines are missing | The device used its daily budget, or low-severity lines reached their 80% share. | None. The budget is counted per device and per UTC day. |

## Related

- [Real user monitoring and Web Vitals](https://noxtica.com/docs/observability/rum/) — the RUM switches this page relies on.
- [Session replay: setup, masking and playback](https://noxtica.com/docs/observability/session-replay/) — the Replay session ID filter links console lines to a recording.
- [Data subject scope, erasure requests and account deletion](https://noxtica.com/docs/compliance/requests-and-deletion/) — erasure requests for people.
- [Privacy](https://noxtica.com/privacy/) — the public privacy policy.

---

Source: https://noxtica.com/docs/observability/session-replay/
Markdown: https://noxtica.com/docs/observability/session-replay/index.md
Last updated: 2026-10-27

# Session replay: setup, masking and playback

Session replay records a masked reconstruction of a visit so an analyst can watch it later. A tenant administrator records the legal basis and sets the policy for each domain, a web developer installs the browser pieces, and analysts play sessions back in Backoffice.

## What it is

Availability: Controlled availability. Replay is off until it is armed for a domain, and it runs when enabled for your organisation.

The recorder runs in the visitor's browser, from the extensions script. It captures page structure, input events and console and network metadata, masks them before they leave the page, and uploads them in chunks to the ingest host. The collector applies the masking and block rules again on its side, whatever the browser sent. Analysts play the result back in Backoffice.

Three settings arm capture for a domain:

1. An active replay legal basis recorded by a tenant administrator.
2. An enabled replay policy on the domain.
3. The platform-wide recording service, which Noxtica operates. You cannot read its state in Backoffice.

Arming is not enough on its own. Each visit must also pass four checks before anything is stored:

- **Consent.** On domains whose client consent mode is `api` or `cookie`, the visitor's `replay` category must be granted. The `replay` category is the one your consent banner controls.
- **Do Not Track and Global Privacy Control.** With the policy set to Honor, a visitor who sends either signal is excluded. The browser checks this and the collector checks it again.
- **Sampling.** The sample rate decides which visitors are drawn.
- **Minimum duration.** A session shorter than the configured minimum is not recorded.

Replay records sampled visits, not every visit, and it is not a complete record of everything a visitor saw. Treat what you watch as evidence to review, not as a verdict.

## Prerequisites

- **Roles.** A tenant administrator records the replay legal basis. A superadmin cannot record it for the tenant. Changing the policy needs the Admin role and a fresh step-up verification. Listing sessions needs the Analyst role or higher. Playing a recording needs the separate replay-payload permission, held by Admin, plus a fresh step-up verification.
- **Browser install.** The core script and the extensions script are loaded and the page allows the ingest host in its Content Security Policy. See [Install & Browser Runtime](https://noxtica.com/docs/browser-runtime/) and [Content Security Policy, hosts and relay](https://noxtica.com/docs/sdk/csp-and-relay/).
- **Consent.** If the domain uses a consent mode, your banner can grant the `replay` category. See [Consent modes, GPC and Google Consent Mode](https://noxtica.com/docs/sdk/consent/).
- **Plan.** A save that asks for more sessions per day than your plan allows is refused. Backoffice shows the values in force.
- **Flags.** Live replay and Feature Flags are separate switches. Both work when enabled for your organisation.

## Steps

### 1. Record the replay legal basis

Backoffice → Privacy & Legal → Legal Basis Register → **Replay legal basis**.

1. Choose the **Domain**.
2. Set **Action** to **Record a legal basis**.
3. Enter the **Legal basis reference (DPA / DPIA)**. Use the real reference. A placeholder is refused.
4. Tick the acknowledgement of the disclosure text and select **Record legal basis**.

Recording a legal basis does not turn replay on. To change it later, choose **Replace the active basis**. To stop capture for the domain, choose **Revoke the active basis**: the record stays for the audit trail and capture stops until a new basis is recorded. Details are in [Legal basis register and receipts](https://noxtica.com/docs/compliance/legal-basis/).

### 2. Add the recorder head (optional, for early capture)

The recorder head is a small synchronous script that buffers early page activity in memory, with no network transport. Without it, the recorder starts later and misses the earliest page activity.

Copy the tag from Backoffice → Integrations & API → Script & Consent → **Snippets**. The stable tag and the pinned variant are documented once, in [Replay recorder head](https://noxtica.com/docs/browser-runtime/#replay-recorder-head) on the install page; this page does not repeat the tag.

- Place it before every other script in `<head>`. Never add `async`, `defer` or `type="module"`.
- `data-cfasync="false"` stops Cloudflare Rocket Loader from deferring it.
- It keeps at most 256 events and 64 KiB. If the core script does not take the buffer within 60 seconds, the buffer is discarded.
- The core script drains the buffer after the consent, legal-basis and policy checks pass. If a check fails, it discards the buffer.

### 3. Grant the replay category from your banner

Call this when the visitor accepts session replay:

```js
window.noxticaClient.setConsent({ replay: 'granted' });
```

`window.noxticaClient.setReplayConsent(false)` withdraws consent: the recorder detaches and its in-memory buffers are cleared before the call returns.

### 4. Set the domain's replay policy

Backoffice → Web Analytics & Privacy → Capture Policies → **Session replay policy**.

1. Pick the domain.
2. Switch **Enabled** on.
3. Set **Requires end-user consent** and **DNT/GPC policy**.
4. Choose the **Masking mode** (next step).
5. Set the limits below, then select **Save replay policy** and complete the step-up verification.

If the domain has no active legal basis, the save is refused, nothing changes and the form returns to the last saved values. Turning replay off needs no legal basis.

| Field | What it does | Bounds | Form default |
| --- | --- | --- | --- |
| Pre-roll (ms) | Activity before the recording starts, kept in a memory buffer. 0 turns it off. | 0 to 60,000 | 5,000 |
| Minimum session duration (seconds) | Sessions shorter than this are not recorded. 0 records every session. | 0 to 600 | 30 |
| Sample rate (ppm) | Share of visitors drawn. 1,000,000 is 100%. | 0 to 1,000,000 | 1,000,000 |
| Max session bytes | Size ceiling for one session. | 524,288 to 26,214,400 | 5,242,880 |
| Max chunk bytes | Size ceiling for one upload chunk. | 16,384 to 262,144 | 65,536 |
| Max chunks per session | Chunk count ceiling for one session. | 1 to 512 | 128 |
| Max sessions per day | Daily session ceiling for the domain. | 1 to 10,000 | 500 |
| Max bytes per day | Daily byte ceiling for the domain. | 1,048,576 to 53,687,091,200 | 2,147,483,648 |
| Retention (days) | Recordings expire this many days after creation. | 1 to 90 | 7 |
| Session tag keys (allow-list) | Tag keys the site may set. See [Custom events, session tags and request tracing](https://noxtica.com/docs/observability/events-and-tracing/). | 32 keys at most | empty |

Bounds can change. Backoffice shows the values in force.

**Requires end-user consent.** Leave it off to record without per-visitor consent. Turn it on when each visitor must have consented. The banner consent satisfies it on domains whose consent mode is `api` or `cookie`. On other domains a per-subject grant written by your controller is needed, and without one nothing is recorded. Visitors who send a DNT or GPC signal are excluded either way when the policy is Honor.

**Sampling and anonymous visitors.** The draw is made per identified subject. Any effective rate below 100% records no anonymous web visitors. To record anonymous visitors, keep the sample rate at 1,000,000 ppm. The effective rate is also bounded by the domain's capture level; see Client Computation Cost Levels in Backoffice.

**Daily quota.** When the session ceiling is reached, Session Replay shows a banner and recording resumes at 00:00 UTC.

The same card also holds **Rehost page assets (CSS, fonts, images)** and **Capture network request/response bodies**. Both are off by default. Body capture applies to fetch and axios calls your code wraps with the capture plugin, and to structured text bodies.

### 5. Choose the masking mode and mark sensitive elements

The **Masking mode** has three values:

| Mode | What replays show |
| --- | --- |
| Strict (default) | Page text, typed input values and URL query strings are masked before they leave the browser. Images are blocked and keep their layout. |
| Standard | Page text and full URLs are visible, with identifier-shaped tokens redacted. Typed input values stay masked. |
| Full fidelity | Page text, full URLs and typed input values are visible. |

In every mode, password and secret fields stay masked. That includes card and one-time-code fields and fields whose name, id or autocomplete value looks like a password, token or similar secret. The exact length of a masked value does not leave the browser. Any element you mark with the attributes below stays masked too.

Relaxing the mode needs an active legal basis with a real reference and a risk acknowledgement that Backoffice asks for on save. Tightening it asks for confirmation: sessions already captured under the looser mode are permanently deleted by replay retention and this cannot be undone. Changing the mode does not change the consent setting.

Mark elements in your page:

```html
<div data-nox-mask>Order notes</div>
<div class="nox-mask">Account number 12345</div>
<section data-nx-replay-obscured>Support chat</section>
<aside data-nx-replay-hidden>Card form</aside>
<aside data-nx-replay-block="card-form">Billing panel</aside>
```

| Marker | Effect |
| --- | --- |
| `data-nox-mask`, class `nox-mask`, `data-nx-replay-obscured` | Text and input values inside the element are masked in every mode. |
| `data-nx-replay-hidden` | The element keeps its tag as an outline. Its attributes (except `class`) and all children are removed from the stored recording. No policy setting is needed. |
| `data-nx-replay-block="<token>"` | Same removal, for tokens listed under **Hard-block selector tokens** in the policy. Tokens use letters, digits, `_` and `-`, up to 128 characters, and the list holds up to 64 tokens. |

Narrowing capture never needs permission, so the hidden marker works without a policy entry.

### 6. Check the recorder in the browser

In the page, with the visitor's consent granted:

```js
window.noxticaClient.getReplayConsentState(); // 'POLICY_READY' when the recorder may start
window.noxticaClient.getReplayRecorderState(); // 'active' while recording
```

| `getReplayConsentState()` | Meaning |
| --- | --- |
| `UNINITIALIZED` | The policy fetch has not settled. |
| `DISABLED` | Capture is refused or opted out for this visit. |
| `AWAITING_CONSENT` | The server allows capture and waits for the visitor's decision. |
| `DENIED` | The visitor declined. This state is final for the client. |
| `POLICY_READY` | The recorder may run. |

`getReplayRecorderState()` returns `idle`, `loading`, `active`, `stopped` or `error`.

### 7. Find and play sessions

Backoffice → Session Insights → **Session Replay**. The page has two tabs: **Sessions** and **Install & status**. The status tab lists each domain as **Armed**, **Not armed** or **Not configured** and shows whether consent is **Required** or **Not required**.

- **Sessions.** The **Recorded sessions** list shows Session, Domain, State, Recorded, Duration, Size, Expires, Signals and **Playable**. Signal badges count rage, dead, error-click, quick-back, excessive-scroll and mouse-thrash events. **Advanced search** opens an omni-search over server-indexed, privacy-safe signals, and **Segments** saves a filter set under a name. Open a row to reach the player.
- **Player.** The session page shows the recording and a **Session events** area with the tabs Overview, Console, Network, Network detail, Exceptions, Performance, Long tasks, Backend logs and Access log. **Access log** lists who read the recording's bytes. Add `?t=<ms>` to the page address to open at a time offset. **View console logs for this session** jumps to the console lines.
- **Review aids.** **Flag for recommendations** marks a session so similar sessions are suggested.
- **Live Assist.** Backoffice → Session Insights → Session Replay → **Live Assist** lists sessions that are recording now. The visitor must grant sharing before anything of their page is visible. Your page loads the live runtime separately with `window.noxticaClient.loadReplayAssist()`, and the visitor is asked for their own consent.

An analyst sees the list and session details. Playing the recording needs the replay-payload permission and a step-up verification, and Backoffice says so when a role lacks it.

### 8. Review retention, quotas and deletion

- **Retention.** Recordings expire after the policy's **Retention (days)**. The default is 7 days on every package. A session past its deadline shows **This recording has passed its retention deadline**.
- **Delete one or many.** **Delete recording** and the bulk delete in the list remove recordings permanently. Their stored chunks are queued for physical deletion. The action needs the manage-replay permission, held by Admin.
- **Purge.** Backoffice → Web Analytics & Privacy → RUM Data Lifecycle offers a scoped purge of the replay data. Preview the matching session count before you run it. A purge cannot be undone and can empty the Session Replay list.
- **Requests about a person.** Use the data subject workflow in [Data subject scope, erasure requests and account deletion](https://noxtica.com/docs/compliance/requests-and-deletion/).
- **Usage.** Replay is metered. See [Usage, quotas and metering](https://noxtica.com/docs/billing/usage-and-quotas/).

### 9. Optional: feature flags and conditional recording

Backoffice → Administration → **Feature Flags** controls per-domain visitor experiences, experiment splits and conditional-recording keys. It works when enabled for your organisation, and a new flag starts off.

## Verify it works

1. In Session Replay → **Install & status**, the domain shows **Armed**.
2. In the page, `getReplayConsentState()` returns `POLICY_READY` and `getReplayRecorderState()` returns `active`.
3. After a visit longer than your minimum duration, a session for the domain appears under **Sessions**, and its **Playable** column reads Playable.
4. Open it. The recording shows your page with masked text and inputs, and the **Access log** tab shows your own read.
5. A password field and any element you marked show masks, not values.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| **Session replay has never been armed** | No domain in the tenant has an active replay legal basis. | Record it in step 1, then enable the policy. |
| **Recording is off for every domain** | No domain has the policy enabled. | Switch **Enabled** on in Capture Policies. |
| **Recording is armed but waiting on consent** | Every armed domain requires consent and no consent signal has arrived. | Grant the `replay` category from your banner, or turn off **Requires end-user consent** if your legal basis allows it. |
| **Recording is armed but the sample rate is zero** | The sample rate is 0, so no visitor is drawn. | Raise the sample rate. |
| **Recording is on, but nothing has been captured** | The configuration is sufficient. The platform recording service or an outdated collector on the visitor's page is the remaining cause. | Ask your account team to check the recording service. Check that visitors load the current core script. |
| Save refused: no active legal-basis receipt | Policy changes that arm or relax capture need a recorded basis. | Record it under Privacy & Legal → Legal Basis Register. |
| Save refused: the reference is a placeholder | Relaxing masking or turning off required consent needs a real DPA or DPIA reference. | Replace the legal basis with a real reference. |
| Save refused: sessions per day exceed the plan | The value is above your plan's ceiling. | Lower the value or ask your account team. |
| Banner: **Replay quota exhausted for today** | The daily session ceiling was reached. | Recording resumes at 00:00 UTC, or raise the limit within your plan. |
| Anonymous visitors never appear | The effective sample rate is below 100%. | Use a 1,000,000 ppm sample rate. |
| Player says you can see metadata but not the recording | Your role lacks the replay-payload permission. | Ask an administrator to grant it. |
| `window.__noxticaHead` appears after the page has already painted | Cloudflare Rocket Loader deferred the recorder head. | Add `data-cfasync="false"` and keep it before every other script, synchronous. |

## Who it fits

Replay adds context to a signal. It does not replace the signal or your policy. It is a separate data path from risk lookups and has its own admission gates.

- **What happened around a risk signal?** A score tells you what changed. A replay can help explain where it happened and what the visitor experienced.
- **Where did a journey break?** Interaction evidence and diagnostics can help support and engineering teams find the step that failed.
- **Can support join a live session?** For eligible in-progress sessions, a live view can support consented investigation. It asks for its own consent and a separately authorised role. See Live Assist in [step 7](https://noxtica.com/docs/observability/session-replay/#7-find-and-play-sessions).

## How teams connect

Replay uses the same browser collector as the rest of Noxtica. You connect it in three places:

- **Your pages.** Load the browser scripts and, for early capture, the recorder head. See [step 2](https://noxtica.com/docs/observability/session-replay/#2-add-the-recorder-head-optional-for-early-capture) and [Install & Browser Runtime](https://noxtica.com/docs/browser-runtime/).
- **Your consent tool.** Report replay consent through the browser consent call. See [step 3](https://noxtica.com/docs/observability/session-replay/#3-grant-the-replay-category-from-your-banner) and [Consent modes, GPC and Google Consent Mode](https://noxtica.com/docs/sdk/consent/).
- **The Noxtica console.** Set the replay policy, masking, sampling and retention. See [step 4](https://noxtica.com/docs/observability/session-replay/#4-set-the-domains-replay-policy) and [step 5](https://noxtica.com/docs/observability/session-replay/#5-choose-the-masking-mode-and-mark-sensitive-elements).

## Limits

Replay records sensitive interaction content. These limits apply to every deployment.

- Controlled availability. Recording is off until a tenant enables it, and access is agreed with Noxtica for each tenant.
- You are responsible for notices, consent, masking, sampling and retention. You must also make sure special-category data and government identifiers are not recorded without a lawful basis.
- A replay is a reconstruction of page structure and interactions, not a video. Some styles, images or elements may not appear as the visitor saw them. Sampling and plan limits apply.

## Common questions

### Does replay record every visitor?

No. Replay records sampled visits that pass every admission check. See [What it is](https://noxtica.com/docs/observability/session-replay/#what-it-is) and [step 2](https://noxtica.com/docs/observability/session-replay/#2-add-the-recorder-head-optional-for-early-capture).

### Who decides how much is masked?

Your team does. **Masking mode** is a tenant setting; see [step 5](https://noxtica.com/docs/observability/session-replay/#5-choose-the-masking-mode-and-mark-sensitive-elements). Review the setting with your privacy advisers.

### Does monitoring consent also cover replay?

No. Replay has its own consent category, `replay`, separate from `analytics`, which covers RUM and other monitoring. See [Consent modes, GPC and Google Consent Mode](https://noxtica.com/docs/sdk/consent/).

## Related

- [Observability overview: RUM, replay, APM and ingest](https://noxtica.com/docs/observability/overview/) — where replay sits among the other tools.
- [Custom events, session tags and request tracing](https://noxtica.com/docs/observability/events-and-tracing/) — tags, identity hashes and timeline events that appear in replay.
- [Behavior analytics: heatmaps, journeys and funnels](https://noxtica.com/docs/observability/behavior-analytics/) — heatmaps can show a masked page background from a recording.
- [Legal basis register and receipts](https://noxtica.com/docs/compliance/legal-basis/) — the register behind step 1.
- [Install & Browser Runtime](https://noxtica.com/docs/browser-runtime/) — recorder head, consent categories and storage keys.
- [Privacy](https://noxtica.com/privacy/) and [Cookies](https://noxtica.com/cookies/) — the public policies.

---

Source: https://noxtica.com/docs/observability/events-and-tracing/
Markdown: https://noxtica.com/docs/observability/events-and-tracing/index.md
Last updated: 2026-10-27

# Custom events, session tags and request tracing

This page is for a web developer who wants to add context to what Noxtica records: named events from your own code, tags and a hashed identity on a session, and a trace header that links a browser request to your backend. A tenant administrator allow-lists what the domain accepts.

## What it is

Availability depends on your plan, role and the modules enabled for your organisation. Events and tags ride on the behavior analytics and session replay lanes, which run when enabled for your organisation.

| API | Where you call it | What it does |
| --- | --- | --- |
| `track(name, properties)` | `window.noxticaClient` | Sends a custom app event. The domain's allow-list decides what is kept. |
| `noxtica('event', name, value)` | Command queue | Adds a replay timeline marker and sends an app event named `name` with a `value` property. |
| `noxtica('set', key, value)` | Command queue | Tags the session with a key and one or more values. |
| `noxtica('identify', id, { hint })` | Command queue | Links the session to a hashed identity. The raw id never leaves the page. |
| `noxtica('metadata', callback, options)` | Command queue | Hands your code the Noxtica session ids. |
| `noxtica('upgrade', reason)` | Command queue | Asks replay to start now, within the policy. |
| `withRequestSpan(url, callback)` and `spanFetch(url, init)` | `window.noxticaClient` | Add a W3C `traceparent` header to a request to an allow-listed origin. |

The command queue also takes `pause`, `resume`, `stop`, `start` and `consent`. The queue is documented in [Client API, events and the command queue](https://noxtica.com/docs/sdk/client-api/).

Three limits shape everything on this page:

- Events and tags are not delivered when the visitor has not consented to the `analytics` category (events) or `replay` category (tags and the replay timeline) in a consent-gated mode.
- A visitor who sends Do Not Track or Global Privacy Control is excluded when the domain policy is Honor.
- Nothing here bypasses consent, sampling or the replay minimum duration.

## Prerequisites

- **Scripts.** The core and extensions scripts load on the page. The tracker, replay and session API run from the extensions. See [Install & Browser Runtime](https://noxtica.com/docs/browser-runtime/).
- **Events.** The domain's **Tracker** switch and its **App events** switch are on, and the domain has an allow-list. The Admin role changes them.
- **Tags and the timeline.** Replay is armed for the domain. See [Session replay: setup, masking and playback](https://noxtica.com/docs/observability/session-replay/).
- **Tracing.** The domain lists the exact origins that may receive a trace header. The Admin role and a fresh step-up verification change the list.
- **Consent.** Your banner grants the categories the features need. See [Consent modes, GPC and Google Consent Mode](https://noxtica.com/docs/sdk/consent/).

## Steps

### 1. Define the command queue before the core script

```html
<script>
  window.noxtica = window.noxtica || function () {
    (window.noxtica.q = window.noxtica.q || []).push(arguments);
  };
</script>
```

The core replays queued calls in order once it starts, then replaces the stub with a live function. An unknown command name logs a warning and does nothing. A failing call reports through the `noxtica:error` event and never throws into your code.

### 2. Allow-list events and properties

Backoffice → Administration → Domains → open the domain → **Configuration** → **Tracker policy**. Switch on the domain's **Tracker** and **App events**. The **Tracker** switch is also in the **Tracker** column of the Domains list.

Backoffice → Web Analytics & Privacy → **Tracking Allowlists** → **Tracker app-event allowlists**.

1. Pick the domain.
2. Choose **Restrict to an allowlist** under **Event name allowlist** and add names such as `checkout_completed`.
3. Do the same under **Property key allowlist** for keys such as `plan`.
4. Select **Save allowlists** and complete the step-up verification.

How the lists act:

| Mode | Behaviour |
| --- | --- |
| **Accept all (legacy default)** | Every name and property is accepted. Domains created before the allow-list existed start here. |
| **Restrict to an allowlist** | An event whose name is not listed is dropped on the server, and the rest of the batch is unaffected. A property key that is not listed is stripped, and the event is kept. |
| **Deny-all** | An empty restricted list. Every event is dropped. A newly created domain starts here. |

Each list holds up to 200 entries of up to 128 characters. A save over the limit is rejected, never truncated. The data of one event is limited to 1 KB.

### 3. Send events

```js
// A custom event with properties. Throws a TypeError for an invalid shape.
window.noxticaClient.track('checkout_completed', { plan: 'pro' });

// A timeline marker plus an app event named 'coupon_applied'.
noxtica('event', 'coupon_applied', 'SPRING');
```

- `track` needs a non-empty string name and a plain object for `properties`.
- `noxtica('event', name, value)` takes a name up to 128 characters. The value is a string (cut at 256 characters), a finite number or a boolean. The event reaches the app-event lane as `track(name, { value })`, so list `value` in the property allow-list to keep it.
- The browser buffers up to 50 events and flushes about every 10 seconds.
- Timeline markers appear in the recording while the recorder is active.

### 4. Tag sessions

Allow the keys before you set tags. Backoffice → Web Analytics & Privacy → **Capture Policies** → **Session replay policy** → **Session tag keys (allow-list)**: up to 32 keys. An empty list turns tags off for the domain.

```js
noxtica('set', 'plan', 'pro');
noxtica('set', 'cohort', ['north', 'eu']);
```

| Rule | Limit |
| --- | --- |
| Key pattern | `A-Z a-z 0-9 _ . : -`, 1 to 64 characters |
| Value | A string, number or boolean, up to 255 characters |
| Values per key | Up to 128 distinct values |
| Keys per session | Up to 32 |

A call replaces the values of that key. An empty list removes the key. An invalid key throws a `TypeError`. A key that is not on the allow-list is dropped. Tags are free text. The server redacts values that look like email addresses or long digit runs, and you should not put personal data in a tag. Tags are attached to the recorded session and need an active recorder.

### 5. Identify a session without sending the raw id

```js
noxtica('identify', 'user-8841', { hint: 'us' });
noxtica('identify', null); // clear the identity
```

The browser sends the SHA-256 of the trimmed id (lowercase hex) and a 2-character hint, such as `us***`. The id may be up to 256 characters. If the browser has no WebCrypto, which is the case on an insecure page, the call does nothing and the raw id is still never sent.

This is the session identity. It is separate from the account id that links a device to a verdict, which you set with `window.noxticaClient.setAccountId(id)`. See [Client API, events and the command queue](https://noxtica.com/docs/sdk/client-api/).

### 6. Read the Noxtica session ids

```js
noxtica('metadata', function (meta) {
  // meta.sessionId, meta.replaySessionId (null until a recording starts),
  // meta.pageId, meta.consent
  myLogger.setContext({ noxticaReplay: meta.replaySessionId });
}, { wait: true, recall: true });
```

`wait` defers the call until a replay session id exists. `recall` calls it again whenever the id changes.

### 7. Start replay now, within the policy

```js
const result = noxtica('upgrade', 'support-chat-opened');
```

The call returns `started`, `already_recording`, `pending_consent` or `refused`. The reason uses the tag-key pattern. It never grants consent, never overrides Do Not Track or sampling, and the minimum duration still applies.

### 8. Allow-list trace origins

Backoffice → Web Analytics & Privacy → **Tracking Allowlists** → **RUM trace controls** → **Trace-origin allowlist**. Add an exact origin: `https://host` with an optional port, with no path and no wildcard. An IP address is rejected, except loopback addresses for local development. The list holds up to 20 origins. Select **Save trace controls**.

### 9. Trace a request

```js
const client = window.noxticaClient;

// Option A: you control the request.
await client.withRequestSpan('https://api.example.com/orders', async ({ headers, span }) => {
  const res = await fetch('https://api.example.com/orders', { headers });
  span.end(res.ok ? 'ok' : 'error');
});

// Option B: let Noxtica issue the request.
const { followed, response, span } = await client.spanFetch('https://api.example.com/orders');
```

- For an allow-listed origin, `headers.traceparent` is set (`tracestate` may be present). For any other origin the callback still runs with empty headers and a no-op span, and the request is not blocked.
- There is no global fetch or XHR patch. You opt in per call.
- The ids are fresh W3C ids. No Noxtica session, tenant or user id enters the header.
- A span ends as `ok` when your callback finishes. A throwing callback ends it as `error` and the error is rethrown. An async callback is awaited for up to 5 seconds.
- `spanFetch` never follows a redirect. On a 3xx it returns `followed: false` and an opaque response. Start a new call for the redirect target.

Your backend continues the trace by reading the `traceparent` header. If it exports OpenTelemetry data to Noxtica, see [APM and the ingestion service (OTLP)](https://noxtica.com/docs/observability/apm-and-ingest/).

### 10. Tag releases

Pass `release` and `buildId` when you create the client. See [Browser errors, console logs and source maps](https://noxtica.com/docs/observability/errors-and-source-maps/).

## Verify it works

1. In Backoffice → Session Insights → Behavior Analytics → Overview, the **App events** feature shows counts after a visit.
2. In a replay of the session, the timeline shows your `event` markers, and the session shows your tags.
3. In the browser network panel, a request to an allow-listed origin carries a `traceparent` header. A request to another origin carries none.
4. `noxtica('metadata', console.log)` prints `sessionId`, `pageId` and `consent`.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| An event never appears | Its name is not on the allow-list, **App events** or **Tracker** is off, the visitor has not consented to `analytics`, or Do Not Track or Global Privacy Control is honored. | Check steps 2 and 3, and the consent state. |
| An event arrives without a property | The property key is not on the allow-list. | Add the key. For `noxtica('event', ...)` add `value`. |
| `track` throws a `TypeError` | The name is empty or `properties` is not a plain object. | Pass a non-empty string and an object. |
| A queued call logs `noxtica:error` | The key, value or reason failed validation. | Match the patterns in the table. |
| A tag is missing | The key is not in **Session tag keys (allow-list)**, the list is empty, or no recorder is active. | Add the key, and arm replay. |
| `identify` does nothing | The id is blank or over 256 characters, or the page has no WebCrypto. | Use a secure page and a valid id. |
| No `traceparent` header | The origin is not allow-listed. The request still runs without a header. | Add the exact origin in step 8. |
| `upgrade` returns `pending_consent` or `refused` | Consent has not been decided, or the recorder cannot start. | Grant the `replay` category. See the replay page. |

## Related

- [Client API, events and the command queue](https://noxtica.com/docs/sdk/client-api/) — the full client surface.
- [Session replay: setup, masking and playback](https://noxtica.com/docs/observability/session-replay/) — tags and markers show up in recordings.
- [Behavior analytics: heatmaps, journeys and funnels](https://noxtica.com/docs/observability/behavior-analytics/) — funnels are built from your app events.
- [APM and the ingestion service (OTLP)](https://noxtica.com/docs/observability/apm-and-ingest/) — backend traces.
- [Single-page apps, frameworks and tag managers](https://noxtica.com/docs/sdk/single-page-apps/) — call these APIs from a framework.

---

Source: https://noxtica.com/docs/observability/behavior-analytics/
Markdown: https://noxtica.com/docs/observability/behavior-analytics/index.md
Last updated: 2026-10-27

# Behavior analytics: heatmaps, journeys and funnels

Behavior analytics shows where visitors click, how far they scroll, which pages they move between and where they drop out of a path. A tenant administrator switches it on for each domain, and analysts read the results in Backoffice. It is aggregate analysis, not a verdict about any visitor.

## What it is

Availability depends on your plan, role and the modules enabled for your organisation. The tracker, heatmaps, journeys and funnels run when enabled for your organisation, and each one has its own switch that starts off.

The tracker is a lane of the extensions script. It runs inside the Sealed Runtime in the visitor's browser and sends batches to the ingest host. It records page views, clicks with the type of the element clicked, scroll dwell, in-page route changes for journeys, page-normalized click and scroll positions for heatmaps, and the app events you send. A tracker session covers one page load: a full page load starts a new session, while route changes inside a single-page app stay in the session. See [Install & Browser Runtime](https://noxtica.com/docs/browser-runtime/) for what the `analytics` category covers and [Privacy](https://noxtica.com/privacy/) for the public policy.

| View | Backoffice name | What it answers |
| --- | --- | --- |
| Tracker overview | Behavior Analytics | How much behavior data a domain sends and from where |
| Click, scroll, dwell, rage and dead-click maps | Heatmaps | Where visitors click and how far they scroll on a page |
| Page-to-page paths | Journeys | Which routes visitors take, and where paths break |
| Ordered app-event steps | Funnels | How many visitors complete each step of a flow |

A heatmap or journey appears for a domain when all of these hold:

1. The domain's **Tracker** switch is on.
2. **Browser interactions** is on. Heatmaps and journeys depend on it.
3. **Heatmaps** or **User journeys** is on. Both start off.
4. The visitor passes the privacy checks. In a consent-gated mode (`api` or `cookie`) the `analytics` category must be granted. A visitor who sends Do Not Track or Global Privacy Control is excluded when the domain policy is Honor.
5. The Sealed Runtime starts on the page, and the sample rate draws the visit.

## Prerequisites

- **Roles.** The Admin role switches the tracker and its features on or off. The Viewer role or higher reads Behavior Analytics, Heatmaps and Journeys. Funnel definitions need the Admin role.
- **Browser.** The core and extensions scripts load, the page allows `'wasm-unsafe-eval'` so the runtime can start, and consent is granted. See [Content Security Policy, hosts and relay](https://noxtica.com/docs/sdk/csp-and-relay/) and [Consent modes, GPC and Google Consent Mode](https://noxtica.com/docs/sdk/consent/).
- **Funnels.** Funnels work when enabled for your organisation. If they are off, the page says so and a Noxtica operator can switch them on for your tenant.
- **Funnel events.** Funnels are built from app events you send. See [Custom events, session tags and request tracing](https://noxtica.com/docs/observability/events-and-tracing/).

## Steps

### 1. Switch on the tracker for the domain

Backoffice → Administration → **Domains**. Switch on the domain's **Tracker** in the list, or open the domain → **Configuration** → **Tracker policy**.

In **Tracker policy**, switch on what you need:

| Switch | Hint in Backoffice | Needed for |
| --- | --- | --- |
| VM telemetry | Collects Sealed Runtime execution telemetry for advanced fingerprint signals | Not needed for the views on this page |
| Debug signals | Verbose debug signals in each submission. It raises payload size. | Diagnosis |
| Browser interactions | Mouse, scroll and keyboard interaction patterns | Clicks, scroll, heatmaps, journeys |
| Heatmaps | Page-normalized click and scroll buckets. Needs Browser interactions. Starts off. | Heatmaps |
| User journeys | Page-to-page transitions and per-session journeys. Needs Browser interactions. Starts off. | Journeys |
| App events | Custom events sent with `track` | Funnels, App events card |

### 2. Set the sample rate

In the same card, set **Sample rate**: the probability from 0.0 to 1.0 that a page view is submitted. 1.0 sends every view, 0.1 about 10%. The default is 1.0. Select **Save**.

The browser refreshes its policy about every 5 minutes, so a change can take a few minutes to reach visitors.

### 3. Read Behavior Analytics

Backoffice → Session Insights → **Behavior Analytics**. Choose a **Domain** and a time window. The page shows your own tenant's data.

- **Overview.** KPIs for Total events, the session count, Batches and VM init success, trends, a device split, top domains, countries, traffic sources and a card per feature such as **App events**. When the domain samples traffic, the page shows a sampling-corrected estimate beside the raw count.
- **Raw batches.** The received batches. Open one to see its events and filter them.
- **Security.** How Sealed Runtime security signals overlap, in a co-occurrence matrix with a minimum-volume floor. It shows no session linkage.
- **Usage guide.** The in-product checklist for enabling the tracker.
- **Live updates.** The page polls about every 5 seconds while it is visible and live updates are on.

### 4. Read Heatmaps

Backoffice → Session Insights → Behavior Analytics → **Heatmaps**.

1. Choose a **Page**, **Device class** (Desktop, Tablet, Mobile), **Map type** and **Window** (24h, 7d, 30d).
2. Read the map. Colour encodes density relative to the busiest bucket on that page.

| Map type | What it shows |
| --- | --- |
| Click | Where visitors click most |
| Scroll | The share of page views that reached each depth |
| Dwell time | How long each section stayed in view |
| Rage clicks | Spots with 3 or more rapid clicks in the same area in one visit |
| Dead clicks | Clicks that led nowhere, with no navigation in the same visit |

- **Heat and Area.** Two ways to draw the same buckets.
- **Compare.** Turn on **Compare** to place two slices side by side, by device or by window.
- **Fingerprint / device ID.** Filter to one device for click and scroll maps. Rage, dead and dwell maps are aggregates and cannot be rebuilt for one device.
- **Show page background.** Paints a masked view of the page, taken from a recorded session, behind the buckets. It reads one replay session, asks you to confirm your identity and is recorded in the audit log. It needs the replay-payload permission, and it shows nothing when no recording of that page exists. See [Session replay: setup, masking and playback](https://noxtica.com/docs/observability/session-replay/).

### 5. Read Journeys

Backoffice → Session Insights → Behavior Analytics → **Journeys**. Choose a domain, **Device class** and **Window**. Journeys follow route changes inside one tracker session, so they do not follow a visitor across full page loads.

- **Flow.** The **Navigation flow** draws page-to-page volumes. Thicker ribbons carry more traffic. A table lists From page, To page, Transitions and Anomaly.
- **Anomalies.** Suspicious transitions, most severe first, rated High, Medium or Low. For example, a network connection that changed mid-session.
- **Recent sessions.** Expand a session to see its steps and connection-change markers.
- **Funnel view.** Choose **Funnel**, add 2 or more pages in order (up to 20), and select **Build funnel**. Each step shows Reach and Drop-off. A step reached by fewer than 5 visitors is hidden as low volume, to protect individual privacy.

### 6. Define Funnels from app events

Backoffice → Session Insights → Behavior Analytics → **Funnels**.

1. Select **New funnel**.
2. Enter a **Name**.
3. Add **Ordered steps (appEvent names)**: 2 to 8 names, each one an app event the domain accepts. Pageview rules are not supported.
4. Add optional **Property filters** as key and value pairs.
5. Set **Window (minutes)**. It cannot exceed the effective retention shown on the page. A longer window is rejected, never silently shortened.
6. Select **Create funnel**, then complete the step-up verification.

Each card shows the conversion, how many entered, a bar or funnel drawing, the share of entry per step and the drop-off to the next step. Counts describe the scanned page of results, not a running total across pages. Drop-off can be hidden when a step has too little volume.

## Verify it works

1. In Behavior Analytics, the Overview shows non-zero Total events and a session count for the domain after a few minutes of traffic.
2. In Heatmaps, the **Click** map of a busy page shows warm buckets.
3. In Journeys, **Navigation flow** lists page-to-page transitions.
4. In Funnels, a funnel on events you have sent shows an entered count.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| **No tracker data found** | The tracker is off, no feature is on, the Sealed Runtime is not enabled, the policy has not refreshed, or sampling is below 100%. | Work through the checklist on the page: **Tracker enabled**, at least one feature, **Sealed Runtime enabled**, wait about 5 minutes, check the sample rate. |
| **Heatmap collection is off** | **Tracker**, **Browser interactions** or **Heatmaps** is off for the domain. | Turn on all three in Domain → Configuration, then allow a few minutes of traffic. |
| **No heatmap rows for these filters** | Collection is on, but the window, device class or map type has no rows. | Try another window, device class or map type. |
| **Showing all domains** | The heatmap aggregates every domain in scope. | Pick a domain in the filter bar. |
| **No journey data yet** | **User journeys** is off, or the runtime has not reported navigation. | Turn it on and wait a few minutes. |
| **Funnels are not enabled** | The funnel feature is off for your tenant. | Ask your account team. |
| Funnel save is rejected with a retention message | The window is longer than the effective retention. | Shorten the window to the value the page shows. |
| A rage, dead or dwell map shows a notice instead of data | A fingerprint filter is set, and these maps are aggregates across visitors. | Clear the fingerprint filter. |
| **Hidden (low volume)** | Fewer than 5 visitors reached the step. | Widen the window or pick pages with more traffic. |
| Show page background says no recorded session exists | Replay recorded no session of that page for that device class in the window. | Session replay records visitors who granted replay consent. |

## Related

- [Observability overview: RUM, replay, APM and ingest](https://noxtica.com/docs/observability/overview/) — how these tools fit together.
- [Custom events, session tags and request tracing](https://noxtica.com/docs/observability/events-and-tracing/) — send the events your funnels use.
- [Session replay: setup, masking and playback](https://noxtica.com/docs/observability/session-replay/) — recordings behind the page background and Issues links.
- [Browser errors, console logs and source maps](https://noxtica.com/docs/observability/errors-and-source-maps/) — the Issues page also groups behavior signals.
- [Domains, site keys and the install card](https://noxtica.com/docs/backoffice/domains/) — where the domain settings live.

---

Source: https://noxtica.com/docs/observability/apm-and-ingest/
Markdown: https://noxtica.com/docs/observability/apm-and-ingest/index.md
Last updated: 2026-10-27

# APM and the ingestion service (OTLP)

Application performance monitoring (APM) lets your backend services send traces, metrics, logs, profiles and release markers to Noxtica over OpenTelemetry (OTLP). A workspace administrator creates a scoped Ingestion API key in Backoffice; your services use it as a bearer token.

This page covers the key, the endpoint, a test request and the Backoffice explorers. Browser real-user monitoring is on [Real user monitoring and Web Vitals](https://noxtica.com/docs/observability/rum/).

## What it is

Availability: In development.

APM capture is not open to every workspace. Where it is enabled for your organisation, the pieces below work as described. Where it is not, Noxtica refuses OTLP requests with `403 apm_purpose_disabled` and the Backoffice explorers stay empty. Ask your account team whether your organisation is enabled.

### Hosts and lanes

The ingestion service answers on `ingest.noxtica.com`. The collector host `collect.noxtica.com` serves the same OTLP routes. The Backoffice setup block pre-fills `ingest.noxtica.com`, and says to treat the collector as a failover only for connection errors that happen before a request is sent. Never switch hosts after a timeout, a lost response or an HTTP error.

| Lane | Route | Used by | You call it |
| --- | --- | --- | --- |
| OTLP traces | `POST /v1/traces` | OpenTelemetry SDKs and collectors | Yes |
| OTLP metrics | `POST /v1/metrics` | OpenTelemetry SDKs and collectors | Yes |
| OTLP logs | `POST /v1/logs` | OpenTelemetry SDKs and collectors | Yes |
| Profiles | `POST /v1/profiles` | Profiling agents and SDKs | Yes |
| Release markers | `POST /v1/deployments` | Your CI or deploy job | Yes |
| Browser telemetry | `/client/*` | The browser SDK | No, see the [browser runtime](https://noxtica.com/docs/browser-runtime/) |

Other products (Hunter, Spot, Pulse) use their own lanes on the same service. They are not covered here.

### Which key does what

| Credential | Prefix | Use |
| --- | --- | --- |
| Ingestion API key | `sk_apm_` | Sends OTLP, profiles and release markers. Server to server only. |
| Server API key | `sk_prod_` | Calls the Noxtica server API. Never accepted on OTLP routes. |

An Ingestion API key is bound to one project and one environment, and accepts only the signals you enable on it. Each key also carries a legal basis you registered for telemetry ingest.

### What is not self-serve

The read and export routes under `/v1/apm/` need the scopes `read:apm` and `write:apm`. Backoffice does not offer those scopes when you create a server API key, so you cannot create such a key yourself today. Whether read or export access is available to you depends on your account; ask your account team. Use the Backoffice explorers to read data.

An OTLP response means the request was accepted into a durable queue. It does not mean the data is already visible in Backoffice.

## Prerequisites

- Administrator role in Backoffice. Creating and revoking keys needs a fresh step-up MFA confirmation.
- APM enabled for your organisation (see the availability line above).
- A registered legal basis for telemetry ingest. A workspace administrator registers it once; Backoffice prompts for it on the key page.
- An OpenTelemetry exporter that can send OTLP over HTTP with a custom `Authorization` header.
- Network egress from your servers to `ingest.noxtica.com` over HTTPS.

## Steps

### 1. Register the legal basis for telemetry ingest

Backoffice → Integrations & API → Ingestion API Keys.

If the page shows "Register the legal basis for telemetry ingest", read the disclosure, tick "I have read this disclosure and assert this lawful basis for my organisation." and press **Register legal basis**. Only a workspace administrator can do this. You can also review it under Backoffice → Privacy & Legal → Legal Basis Register. Without a registered legal basis, key creation is refused.

### 2. Create a project and an environment (optional)

On the same page, open **Projects & environments**.

- A project groups the services of one application. An environment separates where they run. Environment types are `production`, `staging`, `development` and `test`.
- If your workspace has no project yet, your initial key creates a project named Platform with an environment named Production.
- Backoffice shows the project and environment IDs next to their names. You need the environment ID for release markers (the default is `env_production`).
- Archiving a project or environment stops new keys from using it. Existing keys keep working.

### 3. Mint an Ingestion API key

Press **Mint APM ingest key** and fill in the form:

1. Choose the **Project** and **Environment**.
2. Optionally enter a **Key name (optional)** of at most 80 characters, for example `web-01 agent`. The name is never sent with telemetry.
3. Pick a **Preset**, then adjust the signals.
4. Press **Mint key** and confirm step-up MFA.

| Preset | Signals it selects |
| --- | --- |
| Application (OpenTelemetry SDK) | Traces, Metrics, Logs |
| Host agent | Host agent, Metrics, Logs, Traces, Profiles |
| Browser or mobile RUM | RUM events |

All signals you can tick: Traces, Metrics, Logs, Profiles, Deployments, RUM events and Host agent. Add Deployments if the key will send release markers.

Copy the key from the "Copy your key now" panel. Backoffice shows it just once and cannot show it again. Press "I've saved it" when it is stored in your secret manager.

### 4. Point your exporter at the ingestion service

Set these environment variables on the service that exports OTLP over HTTP. They match the "OpenTelemetry HTTP setup" block in Backoffice:

```bash
OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.noxtica.com
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer ${NOXTICA_APM_KEY}"
```

Spans need a `service.name` resource attribute. Noxtica rejects spans that have none, and spans with all-zero trace or span IDs.

The host agent has its own settings (`api_key`, `ingest_endpoint`). Mint the key with the Host agent preset and use the "Where to use this key" panel that Backoffice shows after minting. The agent itself is distributed privately; ask your account team for access.

### 5. Send a test trace

This request uses the JSON form of OTLP. Run it from a Linux shell with the key in `NOXTICA_APM_KEY`:

```bash
NOW=$(date +%s%N)
START=$((NOW - 51000000))
END=$((NOW - 1000000))
curl -sS -i -X POST https://ingest.noxtica.com/v1/traces \
  -H "Authorization: Bearer $NOXTICA_APM_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<JSON
{
  "resourceSpans": [{
    "resource": { "attributes": [{ "key": "service.name", "value": { "stringValue": "checkout-api" } }] },
    "scopeSpans": [{
      "scope": { "name": "docs-smoke-test", "version": "1.0.0" },
      "spans": [{
        "traceId": "W47/95gDgQPSabYzgT/GDA==",
        "spanId": "7uGbfsPBsXQ=",
        "name": "GET /health",
        "kind": "SPAN_KIND_SERVER",
        "startTimeUnixNano": "$START",
        "endTimeUnixNano": "$END",
        "status": { "code": "STATUS_CODE_OK" }
      }]
    }]
  }]
}
JSON
```

Trace and span IDs are base64 strings in the JSON form. Send `Content-Type: application/x-protobuf` for protobuf bodies. Any other content type is refused with `415`. `Content-Encoding: gzip` and `deflate` are accepted.

### 6. Send a release marker

A release marker records that a version of a service went live in an environment. The key must have the Deployments signal. The `environment` value must equal the environment ID of the key:

```bash
curl -sS -i -X POST https://ingest.noxtica.com/v1/deployments \
  -H "Authorization: Bearer $NOXTICA_APM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service":"checkout-api","version":"2026.10.27-1","environment":"env_production","commit":"3f2a9c1d","timestamp":"2026-10-27T09:00:00Z"}'
```

`commit` (7 to 64 lowercase hex characters) and `timestamp` (not in the future) are optional. Unknown fields are refused. The body is limited to 16 KiB.

### 7. Read the data in Backoffice

Backoffice → RUM & APM. The APM tabs are:

| Tab | What it shows |
| --- | --- |
| APM Traces | Distributed traces and span timelines |
| APM Services | Per-service latency, throughput and error summaries, and service dependencies |
| APM Releases | Health of one release at a time, plus the "Deploy markers" list for that release |
| APM Metrics | Gauge, sum and histogram series |
| APM Logs | Log records with severity and trace correlation |
| APM Profiles | CPU, wall, allocation and hang profiles with flame graphs |

APM Errors (backend exception groups) is also routed at `/rum-apm/errors`. In APM Releases you enter an exact release identifier; the page never lists every release for your workspace. Reading needs the Backoffice analytics permission (`view.analytics`, viewer role and up). Use the project and environment selectors above each tab.

### 8. Revoke or replace a key

On the Ingestion API Keys page, press **Revoke key** on a row. Any collector using that key loses access to OTLP ingest immediately. Mint a new key before you revoke if you need zero gap, and swap it in your secret manager.

### 9. Watch usage

Ingestion requests are metered. Backoffice → Billing & Plan → Usage & Quotas shows usage against your plan; see [Usage, quotas and metering](https://noxtica.com/docs/billing/usage-and-quotas/). Limits are configuration and can change; Backoffice shows the values in force.

## Verify it works

- The test trace returns `200 OK`. An empty JSON object `{}` means every span was accepted. A `partialSuccess` object reports how many spans were rejected, for example because of a missing `service.name`.
- The release marker returns `202` with `ok: true`, a `deployment_id` and the stored `service`, `version` and `environment`.
- The key row on the Ingestion API Keys page shows state Active and the signals you chose.
- After a short delay the trace appears in APM Traces for the project and environment of the key, and the service appears in APM Services.
- In APM Releases, enter the release identifier you sent (for example `2026.10.27-1`). The "Deploy markers" panel lists the marker, with the commit if you sent one.

An empty explorer with a `200` response is expected for a short time, and for workspaces where capture is not enabled yet.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| `401 apm_auth_missing` | No `Authorization` header | Send `Authorization: Bearer <key>`. The response carries `WWW-Authenticate: Bearer realm="noxtica-otlp"`. |
| `401 apm_auth_invalid` | Wrong key, a revoked key, or a server API key (`sk_prod_`) instead of an `sk_apm_` key | Mint an Ingestion API key and use it. |
| `401 apm_auth_expired` | The key is outside its validity window | Mint a new key. |
| `403 apm_scope_denied` | The key does not carry the signal you sent (for example logs) | Mint a key with that signal ticked; the signals of an existing key cannot be changed. |
| `403 apm_purpose_disabled` | APM ingest is not enabled for your organisation | Ask your account team. |
| `403 apm_environment_mismatch` on `/v1/deployments` | `environment` differs from the environment ID of the key | Send the environment ID shown in Projects & environments. |
| `415 apm_unsupported_media_type` | Content type is not `application/json` or `application/x-protobuf` (release markers accept JSON only) | Fix the exporter protocol. |
| `413 apm_body_too_large` or `apm_batch_too_large` | A request is over the wire limit of 1 MiB, the decompressed limit of 4 MiB, or 500 spans, points or log records | Lower the exporter batch size. Release markers: 16 KiB. Profiles: 2 MiB wire, 8 MiB decompressed, 20 profiles. |
| `429 apm_rate_limited` | More than 600 requests in 60 seconds for one tenant and project (release markers: 120 in 60 seconds) | Back off and retry after the `Retry-After` interval. |
| `503 apm_queue_unavailable` or `apm_authority_unavailable` | Temporary platform condition | Retry with backoff. |
| `400 apm_malformed_otlp_json` or `apm_malformed_otlp_protobuf` | The body does not decode as an OTLP export request | Check the encoding and the `Content-Type` header. |
| Backoffice refuses to mint: "No legal basis for telemetry ingest is registered" | No legal basis on record | A workspace administrator registers it on the key page (step 1). |
| Backoffice refuses to mint: "Select a project and an environment." | The workspace has several projects | Choose the project and environment in the form. |
| Backoffice: "This project has no active environment." | Environments are archived | Add or restore one under Projects & environments. |
| Explorer is empty, requests succeed | Data is still loading, or capture is not enabled for your organisation | Wait a few minutes; then ask your account team. |

## Who it fits

These are questions APM is planned to help answer. Fit depends on what the finished scope turns out to be.

- **Slow page, unclear cause.** Teams could follow a slow page load to the backend request behind it.
- **Behavior after a deployment.** Release markers could help teams compare behavior before and after a deployment.
- **Session and server data together.** Teams that already use Noxtica for browser monitoring could review backend telemetry beside it.

## How teams connect

Nothing here is a supported setup today. The availability note under [What it is](https://noxtica.com/docs/observability/apm-and-ingest/#what-it-is) says where the steps work.

- **Your services.** Services that already emit OpenTelemetry data would point them at a Noxtica intake with a console-issued key. See [step 3](https://noxtica.com/docs/observability/apm-and-ingest/#3-mint-an-ingestion-api-key) and [step 4](https://noxtica.com/docs/observability/apm-and-ingest/#4-point-your-exporter-at-the-ingestion-service).
- **Your browser sessions.** Browser sessions collected by the Noxtica browser script could be linked to backend traces through standard W3C trace context headers. Trace context would link data but would not decide which tenant it belongs to. See [Custom events, session tags and request tracing](https://noxtica.com/docs/observability/events-and-tracing/).
- **The Noxtica console.** Results would be read in views for traces, metrics, logs and releases. See [step 7](https://noxtica.com/docs/observability/apm-and-ingest/#7-read-the-data-in-backoffice).

## Limits

Read [Who it fits](https://noxtica.com/docs/observability/apm-and-ingest/#who-it-fits) and [How teams connect](https://noxtica.com/docs/observability/apm-and-ingest/#how-teams-connect) as a description of intent. They describe the intended design, not a released workflow.

- APM is in development. Nothing on this page is a commitment on scope or date.
- The planned focus would be linking telemetry to browser sessions, not infrastructure monitoring, general log management or continuous profiling.
- No performance or capacity claims are made on this page. Any such claim would need measurement before publication.
- Traces and logs can carry personal data. Customers would remain responsible for notice, consent, retention and what their services send.

## Common questions

### Can I use APM today?

No. APM is in development. You can ask about early access: see [Contact](https://noxtica.com/contact/).

### Which standards is it planned to use?

The design uses OpenTelemetry transports and W3C trace context. Details could change before any release.

### Will it replace other monitoring tools?

That is not the planned focus. See [Limits](https://noxtica.com/docs/observability/apm-and-ingest/#limits).

## Related

- [Observability overview: RUM, replay, APM and ingest](https://noxtica.com/docs/observability/overview/) for how the observability pages fit together.
- [Real user monitoring and Web Vitals](https://noxtica.com/docs/observability/rum/) for browser-side telemetry.
- [Uptime checks, alerts, status reports and the status page](https://noxtica.com/docs/observability/uptime-alerts-status/) for alert rules on APM metrics.
- [Usage, quotas and metering](https://noxtica.com/docs/billing/usage-and-quotas/) for how ingestion is counted.
- [Authentication](https://noxtica.com/docs/api/authentication/) and [Errors](https://noxtica.com/docs/api/errors/) for the server API.
- [Privacy](https://noxtica.com/privacy/) and [Security](https://noxtica.com/docs/security/) for data handling.

---

Source: https://noxtica.com/docs/observability/seo-tools/
Markdown: https://noxtica.com/docs/observability/seo-tools/index.md
Last updated: 2026-10-27

# SEO tools: page checks, site crawls and search score

The SEO tools in Backoffice check technical search-engine health on hostnames your workspace owns. You can check one page, crawl a hostname in the background, and follow a score that is recomputed after every completed crawl.

Marketing or web teams run them. A workspace administrator starts checks and crawls; viewers can read the results.

## What it is

Availability depends on your plan, role and the modules enabled for your organisation.

The tools live in Backoffice under the sidebar group SEO & Marketing: SEO Check, Site Crawls, Search Console and Search Score. Each page works on one domain at a time; pick the domain in the selector at the top of the page.

| Tool | What it does |
| --- | --- |
| SEO Check | Fetches one page you name and reports a score and a list of issues, most important first. |
| Site Crawls | Crawls a hostname in the background, within a page budget and the rules of robots.txt. |
| Search Score | Shows the latest daily score for each crawled hostname and the issues behind it. |
| Core Web Vitals history | Field (real-user) and lab (single test-browser render) panels under the SEO Check page. |
| Search Console | Connects Google Search Console for a domain. See [Connect Google Search Console for a domain](https://noxtica.com/docs/observability/search-console/). |

Results are signals for your team to review. They are not a ranking forecast and not a verdict on a site.

### Ownership proof

Noxtica fetches only hostnames you can prove you control. It re-checks the proof on every request and never reuses an earlier result.

| Proof | What it covers |
| --- | --- |
| A relay hostname whose DNS TXT verification is active | The whole registered domain (for example `shop.example.com` proves `www.example.com` too). Backoffice labels this "Verified via relay hostname (registrable-domain-level)". |
| A Search Console Domain property (`sc-domain:example.com`) | The whole registered domain. |
| A Search Console URL-prefix property | The exact host of that property, and nothing wider. |

A relay hostname proof is zone-wide, so only verify a relay hostname on a zone you fully control. For relay hostnames, see [Content Security Policy, hosts and first-party relay](https://noxtica.com/docs/sdk/csp-and-relay/).

### Limits you will notice

- A check fetches the page with a 10-second timeout. Running the same URL again within a minute returns the cached result.
- Checks and crawls are each limited to 30 requests per 60 seconds for your workspace.
- A crawl stops at a page budget. The default is 40 pages and the platform bounds it between 10 and 90. Backoffice shows "N of M pages" for each crawl, so the budget in force is visible. Crawls do not promise to cover every reachable page.
- Crawls honour robots.txt for the product token `noxtica`, and honour a `Crawl-delay` of up to 10 seconds.

## Prerequisites

- Role: viewer or higher to read results; administrator to run a check, start a crawl or connect Search Console. Running a check or a crawl does not ask for step-up MFA; connecting Search Console does.
- SEO checks enabled for your organisation. If they are not, Backoffice shows "SEO checks are not available right now".
- Site crawls enabled for your organisation. Without them Backoffice shows "Site crawls are not available in this environment yet".
- A hostname you own, with one of the proofs above.
- The domain added to your workspace under Backoffice → Domains. See [Domains, site keys and the install card](https://noxtica.com/docs/backoffice/domains/).

## Steps

### 1. Prove ownership of the hostname

Choose one:

- Backoffice → Integrations & API → Relay Hostnames: add and verify a relay hostname on your domain.
- Backoffice → SEO & Marketing → Search Console: connect a verified Search Console property for the domain.

Without a proof, checks and crawls answer "Verify hostname ownership first".

### 2. Run a single-page check

1. Backoffice → SEO & Marketing → SEO Check.
2. Choose the domain. The Page URL field is pre-filled with `https://<your-hostname>/`.
3. Enter the full URL of the page, for example `https://example.com/pricing`.
4. Press **Run check**.

The result shows the score, the HTTP status, when the check ran, and how the hostname was verified. Issues are listed with their severity and guidance. The "Recent checks" list below keeps earlier runs with their scores.

A check reviews title and meta description, headings, indexability and canonical tags, images, structured data, security headers, language and viewport tags, and time to first byte.

### 3. Fix the issues and run the check again

Fix the page on your site and press **Run check** again. If you check the same URL within a minute, you see the cached result; wait a minute for a fresh fetch.

### 4. Start a site crawl

1. Backoffice → SEO & Marketing → Site Crawls.
2. Choose the domain and enter the **Hostname to crawl**, for example `example.com`.
3. Leave **Also check pages my robots.txt disallows** off unless you own the domain and need those pages checked. When ticked, Noxtica fetches disallowed pages too and still reports them as "Blocked by robots.txt". The choice is written to the audit log.
4. Press **Start crawl**.

The crawl is queued and runs in the background. The Crawl history shows each run with its status: Queued, Running, Partial, Complete or Failed. A Partial run stopped because of a platform time or request budget and resumes on a later run. A crawl that reaches its page budget is marked Complete even when more pages exist. A crawl re-checks ownership each time it resumes and fails if the proof no longer holds.

The crawl starts from your hostname and from its sitemap, follows internal links, and stays inside the hostname. If the proof covers the whole registered domain, its subdomains are in scope too. It never widens its scope while running.

### 5. Read the crawl

Open a crawl in the history. The detail view lists the pages (with HTTP status, canonical URL, and badges for noindex and "robots.txt blocked", and how the page was discovered: Seed URL, Sitemap or Internal link) and the issues found, each marked Site-wide or Page.

### 6. Follow the search score

Backoffice → SEO & Marketing → Search Score. The page shows the latest daily rollup for each crawled hostname: the mean technical score across the pages the crawl fetched, plus that day's issue counts by severity. Open a hostname to see the issues behind its score. A new rollup appears after each completed crawl. Before the initial completed crawl the page says "No score rollup yet".

### 7. Read Core Web Vitals history

On the SEO Check page, below the check, two panels show history for the hostname you checked:

- **Field Core Web Vitals** uses the Chrome UX Report: real visitors' Largest Contentful Paint, Interaction to Next Paint and Cumulative Layout Shift, rated Good, Needs improvement or Poor.
- **Lab Core Web Vitals** uses one test-browser render of your page: Largest Contentful Paint, Cumulative Layout Shift and Total Blocking Time (a lab proxy).

Lab and field numbers are never merged. Both panels fill only when the sampling that feeds them is enabled for your organisation, and the field panel needs enough Chrome visitors. Otherwise they show "No field Core Web Vitals data yet" or "No lab Core Web Vitals data yet".

### 8. Get alerted when the score drops

Create an alert rule from the SEO score or SEO issue templates. See [Uptime checks, alerts, status reports and the status page](https://noxtica.com/docs/observability/uptime-alerts-status/).

## Verify it works

- A check returns a score from 0 to 100 and an issue list. Each page starts at 100. For each distinct issue code, Noxtica takes off 25 points for a critical issue, 10 for a warning and 2 for an info issue, and never goes below 0.
- If the page could not be fetched, the check shows no score and a message that names the failure class (see Troubleshooting).
- A crawl row moves from Queued to Running and ends at Complete or Partial, with "N of M pages".
- Search Score lists your hostname with a score and a "Computed" time once a crawl completes.

Example issues, by severity:

| Severity | Examples (issue codes) |
| --- | --- |
| Critical | `SEO_STATUS_4XX`, `SEO_STATUS_5XX`, `SEO_TITLE_MISSING`, `SEO_H1_MISSING`, `SEO_NOINDEX_UNEXPECTED`, `SEO_SITE_WIDE_NOINDEX`, `SEO_VIEWPORT_MISSING` |
| Warning | `SEO_REDIRECT_CHAIN_LONG`, `SEO_TITLE_LENGTH_OUT_OF_RANGE`, `SEO_META_DESCRIPTION_MISSING`, `SEO_CANONICAL_MISMATCH`, `SEO_ORPHAN_PAGE`, `SEO_IMG_ALT_MISSING`, `SEO_TTFB_SLOW` |
| Info | `SEO_ROBOTS_BLOCKED`, `SEO_META_DESCRIPTION_LENGTH_OUT_OF_RANGE`, `SEO_STRUCTURED_DATA_ABSENT`, `SEO_OG_TAGS_ABSENT`, `SEO_SECURITY_HEADER_MISSING` |

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| "Verify hostname ownership first" | No active relay hostname or Search Console proof covers the hostname | Complete step 1. A URL-prefix property covers its exact host only; use a Domain property or a relay hostname for subdomains. |
| "Too many checks" or "Too many crawl requests" | More than 30 requests in 60 seconds | Wait a few minutes. |
| "Enter a valid page URL" or "Enter a hostname like example.com" | The URL or hostname is malformed | Enter a full URL with https:// for checks, and a bare hostname for crawls. |
| "SEO checks are not available right now" | SEO checks are not enabled for your organisation | Ask your account team. |
| "Site crawls are not available in this environment yet" | Crawling is not enabled for your organisation | Ask your account team. |
| Check shows "The page took too long to respond" | The page did not answer within 10 seconds | Make sure the server responds quickly, then run it again. |
| Check shows "This page cannot be checked because its address is not a public website address" | The URL resolves to a private or internal address | Use a public https:// URL. |
| Check shows "Your domain's DNS changed during the check" | DNS changed while the check ran, so it stopped for safety | Keep DNS records stable and run the check again. |
| Check shows "The page returned an error status" | The page answered 4xx or 5xx | Fix the page, then run it again. |
| Crawl shows fewer pages than you expected | The page budget was reached, robots.txt disallows pages, or robots.txt could not be fetched | Compare the "N of M pages" count with your site size and check your robots.txt. A host whose robots.txt answers with a server error or a network error is not crawled in that run. |
| Crawl is Failed | Ownership proof lapsed while the crawl was resumed, or a temporary fault | Re-establish the proof and start a new crawl. |
| Field panel shows "Chrome UX Report has no real-user data for this hostname yet" | Too few Chrome visitors | Wait; the panel fills once enough data exists. |
| Search Score says "No score rollup yet" | No crawl has completed for the hostname | Start a crawl and wait for it to complete. |

## Related

- [Connect Google Search Console for a domain](https://noxtica.com/docs/observability/search-console/) for the Search Console proof and position trend.
- [Uptime checks, alerts, status reports and the status page](https://noxtica.com/docs/observability/uptime-alerts-status/) for score alerts.
- [Observability overview: RUM, replay, APM and ingest](https://noxtica.com/docs/observability/overview/) for the rest of the observability pages.
- [Domains, site keys and the install card](https://noxtica.com/docs/backoffice/domains/) for adding a domain.
- [Privacy](https://noxtica.com/privacy/) and [Security](https://noxtica.com/docs/security/) for data handling.

---

Source: https://noxtica.com/docs/observability/search-console/
Markdown: https://noxtica.com/docs/observability/search-console/index.md
Last updated: 2026-10-27

# Connect Google Search Console for a domain

Each domain in your workspace connects to its own Google Search Console property with a credential that you own. A connection is read-only. It proves to Noxtica that you control the hostname, so SEO checks and crawls can run, and it feeds a search position trend.

A workspace administrator does this in Backoffice and in the Google Cloud and Search Console consoles.

## What it is

Availability depends on your plan, role and the modules enabled for your organisation.

Noxtica reads Search Console data with the read-only Google scope `https://www.googleapis.com/auth/webmasters.readonly`. It cannot change a property, a sitemap or a user list.

### One connection per domain

- Every domain row of your workspace has its own connection. Different domains can use different service accounts, OAuth clients or Google accounts.
- Saving a new connection for a domain that already has one replaces it. The old row is kept in a history list (Replaced by a newer credential, Removed, Rejected by Google).
- Backoffice never shows a key or secret again after you save it.

### Credential types

| Type in Backoffice | Use it when | You provide |
| --- | --- | --- |
| Service account (recommended) | You want no human sign-in and no token that expires | A Google Cloud service-account JSON key, added as a user on the property |
| Own OAuth client | You prefer to sign in as a Google user, or your organisation forbids service-account keys | An OAuth client ID and secret from your own Google Cloud project, then Google consent |
| Noxtica Google app (legacy) | Listed only on workspaces where it is still configured | Nothing; an existing legacy connection keeps working, can be removed and cannot be rotated |

### Property types

| Property | Format you type | What it covers |
| --- | --- | --- |
| Domain | `sc-domain:example.com` | The domain and every subdomain |
| URL prefix | `https://www.example.com/` | Exactly its own host |

The property must belong to the domain you connect. A property for another domain is refused with "The property does not match this domain".

### What appears in Backoffice

- The Domains table on Backoffice → SEO & Marketing → Search Console: status (Active, Needs attention or Not connected), credential type, Google account or service account, property, permission level, and Last sync (the time of the last successful Search Analytics fetch).
- The ownership proof for SEO Check and Site Crawls. See [SEO tools: page checks, site crawls and search score](https://noxtica.com/docs/observability/seo-tools/).
- A Search position trend panel under the SEO Check page. It shows the daily average position from your connected properties and says "No search position data yet" until a connected property has reported search results. Noxtica uses Search Console data only and never scrapes search results.

The Search Console page does not include a Search Analytics explorer or a URL-inspection tool.

## Prerequisites

- Administrator role with a fresh step-up MFA confirmation. Adding, rotating, editing and removing a connection each ask for it. The Test action needs the administrator role and no step-up. Platform administrators can view status but cannot change connections.
- The domain exists in your workspace (Backoffice → Domains).
- A Search Console property for the domain that is verified in Google Search Console, on which you or the Google account you use has owner or full access.
- A Google Cloud project you control. Noxtica does not need access to it; it only hosts the service account or the OAuth client.
- Search Console connections enabled for your organisation. If not, Backoffice shows "Search Console features are not available yet" or "Search Console is not set up yet".

## Steps

Open Backoffice → SEO & Marketing → Search Console. The page has two tabs: **Domains** and **Setup guide**. The Setup guide repeats the Google-side steps below.

### A. Service account (recommended)

1. In the Google Cloud Console, choose or create a project. Any project you control works.
2. APIs & Services → Library: search for Google Search Console API and press **Enable**. Without it Noxtica reports that the API is not enabled and names the project.
3. IAM & Admin → Service Accounts → Create service account. Name it, for example, `noxtica-search-console`. It needs no Google Cloud role.
4. Open the service account → Keys → Add key → Create new key → **JSON** → Create. Google downloads the key once.
5. In Google Search Console, choose the property → Settings → Users and permissions → Add user. Paste the service-account e-mail (it ends in `.iam.gserviceaccount.com`) and give it **Restricted** or **Full** permission.
6. In Backoffice, on the Domains tab press **Add** on the domain's row. Keep **Service account JSON key (recommended)** selected, enter the **Search Console property**, upload the key file (or paste its contents) and press **Save and test**. Confirm step-up MFA.

Noxtica checks the key, the property and the permission before it stores anything. The check lists the properties the account can see, requires yours to be among them and verified, and runs one small Search Analytics query. If any step fails, nothing is stored and the message names the cause.

7. When the row shows Active, delete the key file from your machine.

If key creation is disabled in Google Cloud, your organisation enforces a policy against service-account keys. Use the own OAuth client route instead.

### B. Your own OAuth client

1. In your Google Cloud project, enable the Google Search Console API as above.
2. Open APIs & Services → OAuth consent screen (Google Auth Platform in newer consoles). Choose **Internal** if your Google Workspace organisation owns the project, otherwise **External**, and fill in the app name and a support e-mail.
3. Add these scopes: `https://www.googleapis.com/auth/webmasters.readonly`, `openid` and `email`.
4. **Publish the app** (publishing status In production). While an External app is in Testing status, Google expires its access after 7 days and the connection stops working.
5. APIs & Services → Credentials → Create credentials → OAuth client ID → Application type **Web application**.
6. Under Authorised redirect URIs add the exact address shown in the Backoffice dialog (**Authorised redirect URI**, with a **Copy redirect URI** button). It has the form:

   ```text
   https://<your backoffice host>/api/seo/gsc/callback
   ```

   Google compares it character for character.
7. Copy the client ID and the client secret.
8. In Backoffice press **Add** on the domain's row, choose **My own OAuth client**, enter the property, the client ID and the client secret, and press **Continue to Google**. Confirm step-up MFA.
9. Sign in with the Google account that has access to the property and allow read-only access. You return to the Search Console page, which shows the result.

### Test a connection

Press **Test** on a row. Noxtica runs the same check as when you saved. The result shows the property, the permission level and the number of sample rows. A failed test marks the row Needs attention.

### Change the property, rotate the credential or remove it

- **Edit** changes only the property. Noxtica checks the new property with the credential already stored.
- **Rotate** replaces the credential. The property stays the same; use Edit to change it.
- **Remove** stops Noxtica from using the connection. For an OAuth connection, Noxtica revokes its access at Google, then deletes the stored client secret and tokens. For a service account, Noxtica deletes the stored key; the service account stays a user on your property, and the key stays valid in Google Cloud until you delete them there.
- **Show history** lists replaced and removed credentials.

## Verify it works

- The row for the domain shows **Active**, the credential type, the service-account e-mail or Google account, the property and the permission level (Owner, Full user or Restricted user).
- After you press **Test**, a "Test passed" message appears.
- SEO Check and Site Crawls accept the domain's hostname. A Domain property covers subdomains; a URL-prefix property covers its exact host only.
- On an OAuth connection the URL briefly carries the result of the Google sign-in, then Backoffice removes it.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| "The Google Search Console API is not enabled in the Google Cloud project …" | The API is off in the project that owns the credential | Enable Google Search Console API under APIs & Services → Library, wait a minute, retry. |
| "Add <email> as a user on the property …" | The service account is not a user of the property | Add it under Settings → Users and permissions in Search Console. |
| "This credential cannot access that property" | Typo in the property, or no access | Check the spelling. The message lists the properties the credential can see. |
| "That property is not verified in Search Console yet" | The property is unverified | Verify ownership in Search Console. |
| "The property does not match this domain" | The property is for another domain | Use `sc-domain:` for the domain, or a URL-prefix property on this domain. |
| "This credential does not have enough permission on the property" | The user has too little access | Give the service account or user Restricted or Full access. |
| "That is not a valid Search Console property" | Wrong format | Use `sc-domain:example.com` or a full `https://…/` URL. |
| "The service-account key is not valid JSON" or "This JSON file is not a service-account key" | Wrong file, such as an OAuth client file | Upload the JSON key exactly as Google downloaded it. |
| "Google rejected this service-account key" | The key was deleted or disabled | Create a new JSON key and Rotate. |
| "Google did not accept the OAuth client ID or secret" | Wrong values or wrong client type | Copy them again and make sure the client type is Web application. |
| "The redirect URI is not registered on your OAuth client" | The redirect URI differs from the one shown | Add the exact URI from the dialog to Authorised redirect URIs. |
| "Google access was revoked or has expired" | The consent screen is in Testing status, or access was revoked | Publish the app or make it Internal, then Rotate. |
| "Google did not grant offline access" | Google already holds an earlier grant | Remove the app under your Google Account permissions, then connect again and accept every permission. |
| "Access was denied on the Google consent screen" | Consent was refused | Start again and allow read-only access. |
| "This connection request expired or was already used" | The sign-in state is single use | Start again from the Domains tab. |
| Row shows **Needs attention** | Google rejected the stored credential | Press Test for details, then Rotate. |
| "Secure credential storage is not configured for this environment" | Your environment cannot store credentials | Contact Noxtica support. |
| "Platform administrators can view Search Console status but cannot change connections" | You are signed in as a platform administrator | Ask a workspace administrator. |
| Position trend panel is empty | No search results have been reported for a connected property yet | Wait; the panel fills when data exists. |

## Related

- [SEO tools: page checks, site crawls and search score](https://noxtica.com/docs/observability/seo-tools/) for what the proof unlocks.
- [Content Security Policy, hosts and first-party relay](https://noxtica.com/docs/sdk/csp-and-relay/) for relay hostnames, the other ownership proof.
- [Domains, site keys and the install card](https://noxtica.com/docs/backoffice/domains/) for adding a domain.
- [Sign-in, SSO, SCIM, MFA and IP allowlist](https://noxtica.com/docs/security/sign-in-and-access/) for step-up MFA.
- [Privacy](https://noxtica.com/privacy/) and [Security](https://noxtica.com/docs/security/) for data handling.

---

Source: https://noxtica.com/docs/observability/uptime-alerts-status/
Markdown: https://noxtica.com/docs/observability/uptime-alerts-status/index.md
Last updated: 2026-10-27

# Uptime checks, alerts, status reports and the status page

This page covers how you find out that something needs attention: scheduled uptime checks of your own endpoints, alert rules that notify a channel, periodic status-report e-mails, personal notification switches, and Noxtica's public status page.

A workspace administrator sets up checks, channels, rules and reports in Backoffice. Anyone can read the public status page.

## What it is

Availability depends on your plan, role and the modules enabled for your organisation.

| Surface | Where | What it is for |
| --- | --- | --- |
| Uptime Checks | Backoffice → Web Analytics & Privacy → Uptime Checks | Scheduled HTTPS checks of endpoints you own, after you prove ownership |
| Alerts | Backoffice → Integrations & API → Alerts | Channels, rules, delivery history and a privilege-escalation view |
| Status Reports | Backoffice → Integrations & API → Status Reports | Periodic e-mail summaries of your workspace |
| Notifications | Backoffice → Settings → Notifications | Personal switches for e-mail and in-console notifications |
| Status page | `status.noxtica.com` | Public health of Noxtica services, incidents and planned maintenance |

### Gates you may meet

- Alert channels can be created only for channel types that are switched on for your organisation. Until one is, the Alerts page says "Alert channels are not enabled for this platform yet". You can still author rules; they start evaluating once alerting is switched on.
- Uptime probing is an optional capability. Without it, targets stay in the Probing or Disabled state.
- Status-report delivery depends on whether report sending is active for your organisation. Your choice on the page is recorded either way.

### Alert limits

| Limit | Value |
| --- | --- |
| Channels per workspace | 10 |
| Rules per workspace | 20 |
| Channels a single rule can notify | 10 |
| Channel or rule name length in the editor | 80 characters |
| Consecutive failed deliveries before a channel pauses itself | 5 |
| Minimum re-notify interval while a rule keeps firing | 5 minutes (default 4 hours) |

An hourly dispatch cap also applies. Lower-severity alerts are dropped first when it is reached, and the History tab says so. Bounds can change; Backoffice shows the values in force.

### Channel types

| Type | You provide |
| --- | --- |
| Webhook (Generic webhook) | An HTTPS endpoint URL. Noxtica signs each payload; verify the `X-Noxtica-Signature` header. |
| Webhook (PagerDuty) | A PagerDuty Integration Key (32 hex characters). No URL. |
| Webhook (Opsgenie) | An Opsgenie API key and a region (`us` or `eu`). No URL. |
| Slack | A Slack incoming-webhook URL |
| Microsoft Teams | A Teams workflow callback URL |
| Telegram | Your own bot token and a chat ID |
| Email | A Send to address, a Send from address and a Resend API key |

Credentials are stored encrypted and never shown again after you save them. Noxtica does not manage on-call rosters, schedules or escalation policies; PagerDuty and Opsgenie decide routing behind your key.

The Privilege escalations tab on the Alerts page is not paging escalation. It is a read-only view of role changes, cross-tenant reads by platform staff and credit grants or revocations.

## Prerequisites

- Administrator role. Creating, editing and deleting checks, channels, rules and report settings asks for a fresh step-up MFA confirmation.
- For uptime checks: a URL on a domain you own, and the ability to add a DNS TXT record or serve a file under `/.well-known/`.
- For alert channels: the account or key on the receiving side (Slack, Teams, Telegram, Email provider, PagerDuty, Opsgenie or your own endpoint).
- For status reports: a valid e-mail address if you want an external contact.

## Steps

### 1. Add an uptime check

1. Backoffice → Web Analytics & Privacy → Uptime Checks.
2. Enter the **Target URL**. It must be HTTPS, without embedded credentials, and must not point at localhost or a private address.
3. Enter an optional **Label** (up to 120 characters).
4. Choose the **Ownership proof method**: **DNS TXT record** or **.well-known HTTPS file**.
5. Press **Add target**.

Backoffice shows the challenge to publish. For the DNS TXT method, create a TXT record named `_noxtica-uptime-challenge.<host>` with the value shown. For the file method, serve the value as the response body at `https://<host>/.well-known/noxtica-uptime-challenge`. Use **Copy challenge** to copy it.

### 2. Verify ownership and enable the check

1. Publish the challenge.
2. Press **Verify**. A proof stays valid for 30 days; after that you verify again. Verification is limited to 5 attempts per minute for each target.
3. Press **Enable**. A target needs a valid proof before it can be enabled.

A badge shows how many targets are enabled against your allowance (for example `2/5 enabled`). A workspace can hold up to 25 targets. The allowance of enabled targets defaults to 5; Backoffice shows the value in force. Enabled targets are probed on a schedule of about every five minutes.

Each row shows a state: Probing, Up, Degraded, Down or Disabled. Changing a target's URL to a different host clears its proof and disables it until you verify again.

### 3. Add an alert channel

1. Backoffice → Integrations & API → Alerts → **Channels** → **Add channel**.
2. Choose the **Channel type**. For Webhook, pick the **Webhook template**: Generic webhook, PagerDuty or Opsgenie.
3. Enter a **Channel name** and the fields for the type (see the table above), then save.
4. Press **Send test**. The test alert uses the same delivery path as a real alert. For PagerDuty, repeated tests collapse onto one incident.

A channel that fails 5 deliveries in a row pauses itself and shows an auto-paused notice. Fix the cause, then send a successful test to clear it.

### 4. Create an alert rule

1. On the Alerts page open **Rules**. A rule needs at least one channel first.
2. Press **From template** for a curated rule, or **Add rule** for the full editor.
3. Name the rule, set the **Threshold**, **Window** and **Severity** (Info, Warning or Critical), and tick the channels under **Notify these channels**.
4. Save. Each rule shows a state: OK, Pending or Firing.

The curated templates are: Quota usage threshold, High-risk traffic spike, Challenge failure rate, Tracker traffic volume, Honeypot tripwire rate, SEO score dropped below threshold and SEO issue count spiked.

The Add rule editor offers these metric templates: Quota usage, High-risk spike, Flag-hit volume, Traffic volume, Challenge failure rate, Tracker volume, Risk rule fire volume, APM p95 latency, APM error rate, APM throughput drop and APM service down. The template, and so the metric, cannot be changed after you create a rule. APM rules are scoped to one project, one environment and one service.

Daily metrics are evaluated on the last full day. The editor has no template for uptime or browser RUM metrics today.

### 5. Read alert history

Alerts → **History**. Each row shows the time, rule, channel, event (Firing, Resolved or Test), severity and status: Delivered, Queued, Failed, Channel paused or Dropped (cap). Credentials and URLs are never shown.

### 6. Turn status reports on or off

1. Backoffice → Integrations & API → Status Reports.
2. The switch **Send periodic status reports to workspace admins** is on by default. Turn it off to stop reports; your opt-out always wins over the default.
3. Optionally enter a **Nominated external contact** (a further recipient outside your admin list) and a **Display timezone** (an IANA name such as `Europe/Paris`; blank means UTC).
4. Save and confirm step-up MFA. Press **Preview** to render your next report with live data. Nothing is e-mailed.

Reports summarise your own workspace only: traffic, detection activity, usage and quota. Recipients are every active workspace administrator plus the nominated contact.

### 7. Set your personal notifications

Backoffice → Settings → Notifications. Three switches, all on by default: **Critical device email** (e-mail when a device exceeds the configured risk threshold), **In-app alerts** (notifications inside the console) and **Weekly digest** (a summary every Monday at 09:00 workspace time).

### 8. Follow the public status page

Open `https://status.noxtica.com`. It needs no sign-in.

- The banner shows the overall state: All Systems Operational, Degraded Performance, Partial / Major Outage or Some System Status Unknown.
- Each component shows a pill (Operational, Degraded, Down or Unknown) and a 90-day history strip. A table view of the same history is available under each strip.
- Components: Collector API, Backoffice / Dashboard, Website, Verify, Ingestion API and SIEM Event Delivery.
- Incidents and scheduled maintenance windows appear on the page.
- **Subscribe to incidents (Atom)** links to `https://status.noxtica.com/feed.xml`. Add it to a feed reader to follow incidents.

The status page is informational. It is not a contractual service-level agreement. On your Backoffice Home page, a Platform status card shows the same summary for every signed-in role.

## Verify it works

- A verified, enabled uptime target shows Up after the next probe.
- **Send test** shows a success message and a row with event Test and status Delivered in History. The message arrives on the receiving side (Slack message, PagerDuty incident, e-mail, signed request).
- A new rule shows OK. When its condition holds for its window it moves to Pending and then Firing, and History records a Firing row per channel.
- After you save the Status Reports switch, the page shows "Enabled (default)" or "Turned off for this workspace".
- `https://status.noxtica.com/feed.xml` loads as an Atom document, empty when there are no incidents.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| "Alert channels are not enabled for this platform yet" | No channel type is switched on for your organisation | Ask your account team. |
| "Alert evaluation is not turned on for this platform yet" | Alerting is not switched on | You can author rules now; they evaluate after your organisation is enabled. |
| "You have reached the limit of 10 channels" or "of 20 rules" | Workspace limit | Delete one you no longer use. |
| "Enter a valid https:// URL. Localhost and private addresses are not allowed." | Webhook or uptime URL is not public HTTPS | Use a public HTTPS URL. |
| "Enter a valid Slack incoming-webhook URL" | The URL is not on `hooks.slack.com` | Copy the incoming-webhook URL from Slack. |
| Channel shows auto-paused | 5 consecutive failed deliveries | Fix the endpoint or credential, then send a successful test. |
| Test fails ("Could not send the test alert") | Wrong credential, blocked endpoint or provider error | Check the credential and the receiving service. |
| History shows "Dropped (cap)" | The hourly dispatch cap was reached | Reduce noisy rules; lower-severity alerts are dropped first. |
| Rule editor needs a channel | A rule must notify at least one channel | Add a channel first. |
| Uptime: "Ownership check failed (<reason>)" | The record or file is missing or differs | Publish the exact value shown and press Verify again. The reason is one of `proof_mismatch`, `dns_lookup_failed`, `unreachable`, `ssrf_blocked`, `overflow` or `unexpected_status`. |
| Uptime: enabling fails and the message names `ownership_unverified` or `ownership_expired` | No proof, or the 30-day proof lapsed | Verify again, then Enable. |
| Uptime: enabling fails and the message names `uptime_quota_exhausted` | The enabled-target allowance is used | Disable another target, or ask your account team. |
| Uptime: adding fails with "That URL is already registered as an uptime target" | Duplicate URL | Edit the existing target. |
| Status Reports: "Report delivery is not active yet" | Sending is not active for your organisation | Your choice is recorded and applies once sending is active. |
| Status Reports: "Enter a valid email address" or "Enter an IANA timezone name" | Invalid contact or timezone | Correct the value or leave it blank. |
| Status page shows Ingestion API as Degraded | The status probe expects the health endpoint to answer, and an unauthenticated request to the trace route to answer 401 | Check the status page incident list. Contact support if it persists. |
| Privilege escalations tab says "Not armed" | The source is off by default | Ask your account team. |

## Related

- [APM and the ingestion service (OTLP)](https://noxtica.com/docs/observability/apm-and-ingest/) for the APM metrics used by APM alert rules.
- [SEO tools: page checks, site crawls and search score](https://noxtica.com/docs/observability/seo-tools/) for the SEO score used by SEO alert templates.
- [Event sinks (SIEM export)](https://noxtica.com/docs/backoffice/event-sinks/) to forward events to your security tooling.
- [Integrations and API pages](https://noxtica.com/docs/backoffice/integrations/) for the other Integrations & API pages.
- [Sign-in, SSO, SCIM, MFA and IP allowlist](https://noxtica.com/docs/security/sign-in-and-access/) for step-up MFA.
- [Security](https://noxtica.com/docs/security/) for how the status page relates to service commitments.

---

Source: https://noxtica.com/docs/features/
Markdown: https://noxtica.com/docs/features/index.md
Last updated: 2026-09-11

# Customer Capability Reference

Use this page to decide which Noxtica capability families belong in your deployment and what your team will receive from each one. It describes customer-visible behavior, not every implementation detail.

Noxtica is provisioned for an account, tenant, domain, and plan. A capability can be present in the platform without being enabled for your tenant or appropriate for every domain. Treat the status shown in **Backoffice**, the scopes on your API key, and your order form or service agreement as the source of truth for availability. If a page or setting described here is not visible, ask your Noxtica contact whether it requires an entitlement, an operator role, tenant activation, a supported client, or legal-basis review.

## Risk and decisioning

Use this family when signup, login, checkout, content access, or an API operation needs more context than an allow/deny list can provide.

### 01. Risk Scoring

A browser assessment returns a numeric `score`, a five-level `risk_level`, a separate `confidence` value, and named `flags` or reasons when applicable. The tier is an input to your policy, not a statement about a person's identity or intent.

**Configure and use it**

1. Add each origin in **Backoffice → Domains** and install the collector with that domain's Site Key.
2. Review score distributions and reason categories in **Analytics**, **Fingerprints**, and **Quality & Calibration** before choosing actions.
3. Set different policy thresholds for different customer journeys. A high-value account change can require step-up verification earlier than a read-only page.
4. Start enforcement in observe-only or shadow mode where available, compare proposed actions with known outcomes, and then promote a reviewed policy.

**Outputs and customer value**

- Browser callbacks expose the score, tier, confidence, flags, device handle, and cache state.
- Server lookups expose the current risk assessment and device timestamps for backend policy checks.
- The console provides population distributions, reason breakdowns, and decision history for investigation and policy review.
- Risk-action views show what a configured policy did or would have done, helping teams measure fraud coverage and customer friction before changing enforcement.

**Eligibility and limits**

Core scoring is part of an activated web integration; advanced calibration, metered scoring, and enforcement surfaces depend on plan, role, and tenant configuration. A score is probabilistic and context-specific. It does not guarantee that a visitor is human, fraudulent, or safe, and a particular false-positive rate is not promised unless it appears in your contract and measurement plan.

## Device and browser intelligence

Use this family when you need to recognize returning browser installations, compare device context across sessions, or corroborate an authentication or fraud decision.

**Configure and use it**

- Install the browser collector with the script tag, or ask your account team for the private `@noxtica/sdk` browser wrapper (it is not on a public registry). See [Getting Started](https://noxtica.com/docs/getting-started/) and [SDK family and availability](https://noxtica.com/docs/sdk/family/).
- Choose the supported collection mode for the customer journey and use `checkOnce()` when you want the configured cache interval respected.
- Use **Fingerprints**, **Compare**, **Population Data**, and device detail views to review the evidence available for a session.
- Link the returned device handle to your own account or transaction only where your disclosed purpose and retention policy permit it.

**Expected outputs**

You receive a tenant-scoped device handle, risk fields, named reason categories, timestamps, and the browser/device context exposed by the applicable API or console view. Optional attestation can add an integrity result that corroborates the device assessment without exposing the underlying challenge method.

**Customer value**

Recognition and comparison help distinguish a familiar installation from a new or inconsistent one, support step-up authentication, and give investigators a repeatable reference across events.

**Eligibility and limits**

Browser storage clearing, private modes, browser changes, operating-system changes, limited APIs, and consent choices can reduce continuity or confidence. A device handle is not a verified natural-person identity. Hardware and mobile attestation require supported clients, an entitled module, and tenant/domain activation; absence of an attestation result must be handled as unknown rather than automatically hostile.

## Bot, abuse, and network defense

Use this family to triage automation, scripted abuse, suspicious infrastructure, and known bot traffic without treating any one network or browser characteristic as proof.

### 02. Bot Detection

Noxtica combines browser consistency, automation, network, device, and interaction evidence into the same calibrated output used by your policy. Privacy browsers, corporate networks, assistive technology, monitoring tools, and approved automation can resemble parts of an abusive pattern, so reason categories should be interpreted together.

**Configure and use it**

- Review **Bot Intel**, **Geo Risk**, fingerprint details, and analytics by domain.
- Connect an eligible reputation source or use the provided network context where your account includes it.
- Define approved automation separately from general traffic, then use policy conditions to allow, observe, challenge, or block.
- Validate actions in shadow mode and monitor customer-support and conversion outcomes after rollout.

**Outputs and customer value**

Outputs include calibrated risk, confidence, explainable bot/network reason categories, known-agent context where available, and aggregate trends. Teams can prioritize abuse queues, protect expensive routes, and allow expected automation without weakening policy for everyone.

**Eligibility and limits**

IP reputation, advanced bot intelligence, emerging-threat reporting, and some feeds can be metered or module-gated. Network reputation changes over time; VPN, relay, mobile, and datacenter use is not inherently malicious. No bot detector catches every automation tool, and Noxtica does not promise frictionless treatment for every legitimate visitor.

## Account linking and investigation

Use this family after detection when an analyst needs to determine whether events, devices, accounts, or infrastructure may be related.

**Configure and use it**

- Begin with **Fingerprints**, **Compare**, and account-associated device history.
- Use linkage, cluster, investigation, OSINT, or geo views only when they are visible for your tenant and your documented legal basis covers the data involved.
- Save the evidence and rationale that matter to your case; do not treat a shared attribute as identity proof.
- Feed confirmed outcomes back through the supported labeling or review surface so future calibration can be evaluated against your traffic.

**Expected outputs**

Customer surfaces can show side-by-side device evidence, event timelines, related-profile or cluster hypotheses, geographic/network context, investigator notes, and exportable case material. These outputs help an analyst move from a single alert to a reviewable account or abuse pattern.

**Eligibility and limits**

Investigation, linkage, raw-network detail, and external enrichment are separately controlled and may require entitlement, an operator capability, recorded legal basis, or explicit tenant opt-in. Relationships are leads, not proof that two accounts belong to the same person. Sparse traffic, shared devices, shared networks, and expiring retention windows can limit conclusions.

## Journey and experience observability

Use this family when risk needs to be understood in the context of a customer journey: what route was visited, what failed, and where friction appeared.

**Configure and use it**

1. Choose a domain in Backoffice and enable only the tracker, real-user monitoring, replay, heatmap, journey, or funnel surfaces included for that domain.
2. Set sampling, capture level, redaction, console/error capture, consent or legal-basis admission, and retention before collecting production sessions.
3. Use **Client RUM**, **Session Replay**, **Runtime Tracker**, **Heatmaps**, **Journeys**, and **Funnels** to move from aggregate performance or risk to an eligible session.
4. Compare operational findings with risk reasons; observability context should inform a decision, not silently become a blocking rule.

**Expected outputs and customer value**

Depending on configuration, outputs can include route and journey summaries, web-performance measurements, error aggregates, replay timelines, heatmaps, funnel progression, and session context attached to an investigation. They help product, fraud, and support teams see whether a security control protected a route or merely created friction.

**Eligibility and limits**

These capabilities are domain-scoped, opt-in, and subject to plan limits, sampling, browser support, consent/legal-basis requirements, redaction, and retention. The small synchronous recorder helper has no transport; capture is admitted or discarded by the configured policy when the asynchronous collector starts. Replay is not a complete record of everything a user saw, and sampled data must not be treated as a full traffic census.

## Monitoring, alerting, and reporting

Use this family to run Noxtica as an operational control rather than checking individual records by hand.

### 03. Operator Console

The Backoffice brings together account health, risk analytics, device records, live monitoring, policy outcomes, alerts, audit history, exports, and usage. Navigation and actions are filtered by the signed-in operator's role and tenant scope.

**Configure and use it**

- Build saved views and domain/time filters around the routes your team owns.
- Configure eligible alert channels, webhooks, or event sinks with the minimum data needed by the destination.
- Use audit and risk-action history to review who changed a setting and how a policy behaved.
- Schedule your own review cadence for false positives, missed abuse, delivery failures, quotas, and retention.

**Outputs and customer value**

Dashboards provide trends and breakdowns; live and alert surfaces identify records needing attention; exports, webhooks, and event sinks move eligible events into customer workflows. Together they support investigation handoff, policy governance, and evidence collection without requiring every stakeholder to query an API.

**Eligibility and limits**

Views depend on role, tenant scope, retained data, and enabled modules. Alerting and event delivery require explicit destination configuration and can be affected by downstream availability or quotas. Audit records document platform activity; they do not by themselves certify compliance with a framework.

## Agent identity and control

Use this family when signed automated agents, AI crawlers, and other machine clients need a different trust policy from anonymous automation.

**Configure and use it**

- In the eligible **Agentic Security** or KYA surface, define which verified agent identities are allowed, denied, or observed for a tenant.
- Associate those trust outcomes with route-specific risk actions rather than applying one global rule.
- Start in observe-only mode, review unknown and failed-verification traffic, then enable challenge or block actions deliberately.
- Keep unsigned or unverifiable traffic in an `unknown` path unless your own policy has other evidence for escalation.

**Expected outputs and customer value**

Customer-visible results distinguish verified, unverified, allowed, denied, and unknown agent states and connect them to policy outcomes and audit records. This lets content, security, and platform teams admit wanted agents while applying stronger controls to unwanted or unverified automation.

**Eligibility and limits**

Know Your Agent, agent verification, and associated enforcement require the module to be included and activated for the tenant. Verification proves possession of an accepted agent credential under the supported protocol; it does not prove the agent's intent, the human behind it, or the safety of every request. Payment or crawl-monetization rails, where separately offered, are optional workflows rather than a detection differentiator.

## AI-assisted operations

Use this family when operators need faster summaries and investigation context inside the console without handing policy control to an autonomous system.

**Configure and use it**

- Enable the assistant only for eligible tenants and operators, select an available provider configuration, and set usage/budget controls.
- Ask it to summarize the Noxtica state the operator can already access, such as policies, domains, recent risk activity, or audit history.
- Verify important findings in the linked console records before changing policy through ordinary operator workflows.
- Review assistant usage and audit/oversight surfaces as part of your access-review process.

**Expected outputs and customer value**

The assistant produces conversational summaries and pointers to relevant customer data under the current operator session. It can shorten investigation setup and explain where to look next while preserving the human decision point.

**Eligibility and limits**

Provider, model, budget, region, and module availability are account-specific. Current assistant tools described in the public documentation are read-only. Generated text can be incomplete or wrong; it is not a verdict, compliance determination, or autonomous enforcement action.

## Developer platform and integrations

Use this family to collect browser context, consume results in your application, or connect Noxtica events and reads to existing systems.

### 04. Fast Verification

The collector loads asynchronously after any required early recorder helper, caches assessments according to configuration, and exposes results through browser events and APIs. Backend services can perform scoped lookups or use supported server SDKs. Performance depends on client, route, cache state, configuration, geography, and network conditions; no universal latency value is implied here.

### 06. Open Integration

Supported customer surfaces include the script-tag loader, the programmatic browser client, scoped Server API keys, browser events, exports, webhooks/event sinks, and a read-only MCP connection for eligible tenants. Framework wrappers, server SDKs, native SDKs and Postman collections are distributed privately through your account team; none of them is installable from a public registry. The public API operations are published as an OpenAPI description at [openapi.json](https://noxtica.com/docs/api/openapi.json). See [SDK family and availability](https://noxtica.com/docs/sdk/family/).

**Configure and use it**

- Copy the current install snippet and Site Key from Backoffice; keep production and non-production origins separate.
- Create the narrowest server key scopes required and keep secret keys off the client.
- Choose browser callbacks for in-page experience, server lookups for trusted backend policy, and event delivery or exports for downstream operations.
- Monitor errors, rate limits, cache behavior, sink delivery, and usage quotas.

**Outputs and customer value**

Integrations deliver typed risk/device responses, lifecycle events, scoped API reads, event records, export files, and read-only agent context. You can place the decision at the right boundary while retaining Noxtica's explainable reasons and tenant scope.

**Eligibility and limits**

Endpoints, scopes, quotas, SDK packages, event sinks, MCP, relay hosts, and offline verification options vary by account and contract. A public Site Key is origin-bound; a Server API key is secret. No self-hosted, air-gapped, or migration guarantee applies unless it is explicitly included in your agreement. See [Getting Started](https://noxtica.com/docs/getting-started/), [SDK family and availability](https://noxtica.com/docs/sdk/family/) and [Backend Integration](https://noxtica.com/docs/backend-integration/) for the current public contract.

### Owned-site search visibility

Run technical checks and site crawls, follow issue trends, and connect read-only Search Console data for an owned property. Checks require verified domain ownership; Search Console features require an approved Google connection.

## Identity verification and access

Use this family when a workflow must collect identity evidence, verify device/app integrity, bind an approved credential, or route an exception for human review.

**Configure and use it**

- Confirm that identity verification is included for the tenant, jurisdiction, evidence type, and platform you intend to support.
- Configure policy and provider requirements before presenting capture, liveness, passkey, mobile-attestation, recovery, or review flows.
- Use verification and review queues to separate completed, inconclusive, rejected, expired, and escalated cases.
- Keep the resulting decision in your own authorization flow; device risk can corroborate identity evidence but should not replace it.

**Expected outputs and customer value**

Eligible flows can return case status, evidence-processing status, provider result, device or app integrity context, passkey state, review disposition, and an audit trail. These outputs help onboarding and access teams route exceptions consistently and keep high-risk changes behind step-up controls.

**Eligibility and limits**

Identity, liveness, mobile, recovery, screening, and passkey surfaces are separately entitled and can depend on an external provider, supported device, geography, evidence quality, role, and policy. Availability in the console does not mean every sub-flow is activated. No result should be described as legal identity proof outside the scope of the configured provider and contract.

## Governance and data controls

Use this family to define who can operate Noxtica, which domains may collect, what data is retained or exported, and what legal/consent conditions admit optional collection.

### 05. Privacy by Construction

Noxtica minimizes and scopes browser/device data, but does not describe all such data as non-personal. A returning-device handle, network context, and browser characteristics can be personal data depending on law and use. Your configuration, disclosures, legal basis, retention, processors, and contract remain part of the control boundary.

**Configure and use it**

- Register exact origins and use separate Site Keys for environments.
- Assign least-privilege roles; enable MFA or configured SSO controls for operators where available.
- Set retention, export, deletion, redaction, consent, DNT/GPC, optional biometric, and raw-network policies for each applicable surface.
- Review **Audit**, **Data Operations**, domain settings, the privacy notice, subprocessor page, and your signed terms together.

**Outputs and customer value**

Governance surfaces expose domain state, roles, sessions, policy/consent receipts, audit events, retention status, exports, deletion workflows, and configuration history. They help security, privacy, and engineering teams establish a reviewable operating record.

**Eligibility and limits**

Specific hosting location, transfer restrictions, deletion timelines, subprocessor commitments, certifications, and data-processing terms come from current legal documents and the customer's contract—not this feature reference. Optional behavioral biometrics and raw network storage require explicit activation and additional review. Exports and audit trails support your controls but do not make a deployment automatically compliant.

## Workspace and commercial operations

Use this family to administer tenants, domains, users, plan modules, quotas, usage, invoices, and available account services.

**Configure and use it**

- Invite or assign operators according to the roles enabled for your account and select the correct tenant before making changes.
- Add domains, inspect module status, and compare current usage with plan or metered limits.
- Use package, wallet, invoice, order, or report surfaces only where they are present for your commercial arrangement.
- Contact Noxtica for provisioning or contract changes that are not offered through your visible account controls.

**Expected outputs and customer value**

Workspace surfaces show tenant/domain status, operator access, active modules, usage and quota records, and eligible commercial documents or balances. This gives account owners one place to understand what is enabled and what operational limit needs attention.

**Eligibility and limits**

Commercial surfaces vary by role, billing arrangement, currency, provider, region, and contract. A module listed in pricing or represented in code is not necessarily available to purchase or activate in your account. No free tier, instant provisioning, self-serve checkout, price, or service level is promised by this page.

## How to choose a starting set

- **Protect a web journey:** start with [Device and browser intelligence](https://noxtica.com/docs/features/#device-and-browser-intelligence), [Risk and decisioning](https://noxtica.com/docs/features/#risk-and-decisioning), and a shadow policy.
- **Investigate abuse:** add [Bot, abuse, and network defense](https://noxtica.com/docs/features/#bot-abuse-and-network-defense), [Account linking and investigation](https://noxtica.com/docs/features/#account-linking-and-investigation), and operational reporting.
- **Understand friction:** add [Journey and experience observability](https://noxtica.com/docs/features/#journey-and-experience-observability) with reviewed capture and retention settings.
- **Govern automated agents:** add [Agent identity and control](https://noxtica.com/docs/features/#agent-identity-and-control) and route-specific enforcement.
- **Connect existing operations:** use [Developer platform and integrations](https://noxtica.com/docs/features/#developer-platform-and-integrations) plus scoped alerts, sinks, or exports.

## Related reading

- [Getting Started](https://noxtica.com/docs/getting-started/) — install the collector and configure domains.
- [Threat categories](https://noxtica.com/docs/threat-categories/) — interpret public reason families without relying on hidden probes.
- [Why calibration, not verdicts](https://noxtica.com/docs/why-calibration/) — turn risk and confidence into a customer-owned policy.
- [Use cases](https://noxtica.com/docs/use-cases/) — apply these families to specific journeys.
- [Engineering principles](https://noxtica.com/docs/principles/) — the operating constraints behind the defaults.

---

Source: https://noxtica.com/docs/impact-audiences/
Markdown: https://noxtica.com/docs/impact-audiences/index.md
Last updated: 2026-09-11

# Impact by Audience

Browser and agent risk controls affect more than the team that configures them. The same assessment can shape a fraud queue, a marketplace rule, an end user's challenge, and an automated agent's access. Use this page to identify the owner, customer surface, expected output, and safeguard for each audience before rollout.

Noxtica supplies evidence and eligible policy controls. It does not establish that a person committed fraud, guarantee a business outcome, or remove your responsibility for authentication, accessibility, privacy, and customer support.

## 01. For companies

> Fraud teams, security engineers, product owners, support teams, and privacy reviewers share the consequences of both missed abuse and unnecessary friction.

### When to use Noxtica

Use it at a defined decision point—such as signup, login, account recovery, checkout, promotion redemption, or an expensive API operation—when device, browser, network, or agent context can improve an existing control.

### Configure through customer surfaces

1. **Domains and API Config:** register exact origins, install the collector, and create narrowly scoped server credentials.
2. **Analytics and Fingerprints:** establish a baseline by domain, route, browser population, and known outcome before enforcing.
3. **Risk Actions and policy settings:** create route-specific allow, observe, challenge, review, or block behavior. Use shadow mode when available.
4. **Quality, audit, and support workflows:** label confirmed outcomes, inspect reasons, review changes, and provide a path for customers whose access was interrupted.

### Expected outputs

- A score, five-level risk tier, confidence, and named reason categories for an assessed session.
- A tenant-scoped device handle and timestamps for eligible backend lookups.
- Population trends, policy-action history, audit records, alerts, and exports where enabled.
- Optional agent, network, behavioral, attestation, or identity context when the applicable module and data policy are active.

### Customer impact

These outputs can help teams prioritize review, apply step-up authentication to unfamiliar or elevated-risk sessions, and preserve low-friction paths for lower-risk traffic. The defensible benefit is better allocation of friction and investigator time—not a promised chargeback, conversion, or detection-rate result.

### Responsibilities and limits

Choose success and harm metrics before rollout: confirmed abuse, challenge completion, abandonment, support contacts, appeal reversals, and unknown/error rates. Do not use a single flag as proof, silently convert a shadow policy into enforcement, or assume an audit log certifies a compliance framework. Availability depends on your plan, configuration, role, and contract. Retention starts at the same default on every package and follows your configuration and contract.

---

## 02. For platforms

> Marketplaces, communities, social products, content businesses, and other multi-sided platforms must protect trust without turning shared devices or unusual access patterns into guilt by association.

### When to use Noxtica

Use it when repeated account creation, coordinated manipulation, promotion abuse, scraping, review abuse, or suspicious seller/buyer activity needs to be triaged across more than one event.

### Configure through customer surfaces

- Associate the returned device handle with the platform event under your own disclosed purpose.
- Use **Compare**, eligible linkage/cluster views, journey context, and investigation tools to review potentially related activity.
- Send medium-confidence cases to observation or moderation; reserve stronger interventions for corroborated evidence and a reviewed platform rule.
- Maintain explicit treatment for shared households, managed workplaces, libraries, schools, VPNs, accessibility tooling, and approved automation.

### Expected outputs

Platform teams can receive event-level risk, related-device or cluster hypotheses, timelines, reason families, and policy outcomes. Analytics can show how the affected population changes after a rule is introduced, while audit and export surfaces preserve the review trail where enabled.

### Customer impact

The practical outcome is a better-ranked moderation or abuse queue and a consistent step-up path for risky actions. Device similarity and network overlap help investigators find patterns, but remain evidence to review—not automatic proof that accounts share an owner or acted together.

### Responsibilities and limits

Shared devices, shared networks, browser resets, sparse histories, and expired data can create both missed links and misleading links. Publish an appeal or recovery path for consequential decisions. Investigation and linkage features can require a separate entitlement, operator capability, recorded legal basis, or opt-in data setting.

---

## 03. For people

> End users experience the policy as a normal journey, an extra check, a delay, or a denial. Their accessibility and privacy needs belong in the acceptance criteria.

### What good operation looks like

- **Proportionate friction:** low-risk traffic keeps the ordinary path; uncertain traffic receives a reversible step-up when appropriate; irreversible action requires stronger evidence.
- **Low-confidence restraint:** missing browser APIs, short sessions, blocked storage, or restricted collection do not become a reason to punish a visitor.
- **Privacy-aware configuration:** optional collection is activated only after the required disclosure, consent or legal-basis review, minimization, redaction, and retention choices.
- **Explainable support:** support staff can locate the relevant assessment, understand its public reason families, and route an appeal without exposing hidden detection methods.

### What people may notice

Most output is consumed by your application or operations team. A person may notice a challenge, an account hold, a request for another factor, or a customer-support review. Noxtica does not guarantee that legitimate users will never see a challenge, and privacy browsers, VPNs, uncommon devices, and assistive technology must not be treated as malicious on their own.

### Data boundary

The collector does not need an email or name to produce a device assessment, but browser/device handles and network context can still be personal data depending on law and use. Your notice should describe the data and purpose actually configured. Review the current legal pages and your signed agreement rather than relying on an absolute “anonymous” or “non-personal” label.

### Measure the impact

Segment challenge completion, abandonment, support contacts, and reversals by domain, journey, browser family, device class, locale, and accessibility feedback where you can do so appropriately. A lower fraud count is not a complete success metric if customer friction or exclusion rises.

---

## 04. For AI and agents

> Owners of legitimate crawlers and automated agents need a predictable way to identify supported agents; site owners need policy that distinguishes verified identity from trust and trust from action.

### When to use Noxtica

Use Know Your Agent when your tenant is entitled and you want explicit allow, deny, or observe treatment for supported signed-agent traffic. Use the read-only MCP integration when your own agent needs scoped access to Noxtica context. These are separate directions of trust.

### Configure through customer surfaces

- Define allowed, denied, and unknown agent treatment in the eligible **Agentic Security** or KYA surface.
- Associate agent state with route-specific risk actions and validate in observe-only mode.
- For MCP, mint a scoped token, apply rate limits, monitor its audit history, and give the agent only the reads it needs.
- For the built-in assistant, rely on the operator's existing role and verify important summaries in the underlying console records.

### Expected outputs and impact

KYA can return verified, unverified, allowed, denied, or unknown agent context for policy. MCP returns scoped read-only platform data; the assistant returns operator-facing summaries. This lets site owners admit wanted automation deliberately and gives agent owners a clearer route than pretending to be human.

### Responsibilities and limits

Agent verification proves the supported credential check, not benevolent intent or authorization for every operation. Unknown is not the same as malicious. Current public MCP and assistant tool contracts are read-only and do not autonomously change customer systems. Agent, MCP, and assistant surfaces are account-specific and may require activation, role, quota, or provider configuration.

---

## Pattern: how one signal serves three audiences

The original three-audience model remains useful; AI and agent owners add a fourth stakeholder for automated traffic.

| Audience      | Where the assessment lands                                                          | Primary safeguard                                                     |
| ------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| Companies     | Signup, login, checkout, recovery, and fraud operations                             | Route-specific policy, shadow validation, and outcome review          |
| Platforms     | Moderation queues, abuse investigations, account-link hypotheses, publication gates | Human review and explicit shared-device/network exceptions            |
| People        | Whether an action proceeds normally, receives a step-up, or enters support/recovery | Confidence-aware restraint, accessibility, disclosure, and appeal     |
| AI and agents | Agent trust policy, crawler access, MCP reads, operator-assistant summaries         | Verified identity separated from authorization; scoped, audited reads |

The same risk assessment can support each audience, but the action, owner, and harm are different. Document those differences in your rollout plan.

## Customer rollout checklist

1. Name the customer journey and accountable policy owner.
2. Confirm module, tenant, domain, role, quota, client, and contract eligibility.
3. Record purpose, data categories, consent/legal basis, retention, and downstream destinations.
4. Baseline risk, confidence, unknown/error rate, abuse outcome, and user-friction metrics.
5. Run observe-only or shadow evaluation where available.
6. Review affected cohorts and false-positive appeals before enabling stronger action.
7. Revisit policy after material traffic, model, integration, or legal changes.

## Related reading

- [Customer capability reference](https://noxtica.com/docs/features/) — where each family is configured and its eligibility boundaries.
- [Threat categories](https://noxtica.com/docs/threat-categories/) — how to interpret public reason families.
- [Use cases](https://noxtica.com/docs/use-cases/) — reference deployment patterns without fabricated customer results.
- [Why calibration, not verdicts](https://noxtica.com/docs/why-calibration/) — why policy remains yours.
- [Engineering principles](https://noxtica.com/docs/principles/) — the operational review standard behind these safeguards.

---

Source: https://noxtica.com/docs/platform-overview/
Markdown: https://noxtica.com/docs/platform-overview/index.md
Last updated: 2026-10-08

# Platform Overview

This page is the reference version of the sections of the Noxtica home page: the customer value framing, the platform tour, evaluation guidance, capability families, principles, session context, AI guardrails, whitepapers, and next steps.

## Customer value

RISK INTELLIGENCE, IN PRACTICE

### Start with the interaction your business cannot afford to misread.

A signup, login, checkout, recovery change, or agent request can carry different risk even after an identity or device check passes. Noxtica calls the layer that turns available interaction evidence into an explainable risk read Agentic Security & Risk Intelligence.

Interaction → evidence → policy → measured cost

THE INTERACTION

### Name the action and the cost of getting it wrong.

Choose one consequential moment: creating an account, signing in, redeeming value, paying, changing credentials, or calling a sensitive route. Define the current control and the costs of missed abuse and unnecessary friction.

THE EVIDENCE

### Give the decision an explainable risk read.

Noxtica correlates the supported browser, device, network, behavior, identity, and agent context available for that interaction, then returns risk, confidence, and reasons. Evidence varies by browser, consent, tenant, and enabled modules.

THE POLICY

### Keep the business decision in your hands.

Your application combines the read with the account, transaction, and journey context it already owns, then chooses whether to allow, observe, step up, review, or block. Optional browser enforcement follows customer-configured policy; it does not invent that policy.

THE COST

### Measure both risk coverage and customer friction.

Use labeled traffic to compare confirmed abuse or fraud, challenge completion and abandonment, review and support work, reversals, and unknown or error states. A useful evaluation makes the trade-off visible instead of celebrating a demo score.

### How to compare the alternatives fairly

Identity, perimeter control, analytics, and interaction risk answer different questions. Keep the tools that already do their job, then test whether an explainable risk read closes a specific decision gap.

#### Identity-only lookup

Use it when recognition, authentication, or continuity is the main question. A valid identity or known device remains evidence; it does not prove the current action is safe or intended.

#### Perimeter and bot controls

Use it for broad traffic controls and in-path enforcement. Add interaction context only where a login, checkout, recovery, or agent action needs a route-specific policy.

#### Analytics and replay tooling

Use it to understand journeys and investigate behavior. Evaluate that job separately from a risk read your application can consume at a live decision point.

**WHAT EACH BUYER SHOULD VERIFY**

FRAUD & RISK

#### Can the evidence improve a real queue or policy?

Choose the abuse pattern, label both legitimate and unwanted outcomes, and compare risk coverage with challenge, review, appeal, and reversal costs.

ENGINEERING

#### Can every result state be handled safely?

Inspect the integration, payload, reason contract, module dependencies, and missing or unavailable paths. Keep secrets and authoritative reads on the server where the decision requires it.

BUSINESS

#### Is the protected outcome worth the operating cost?

Compare missed abuse, customer interruption, review capacity, support impact, and existing-tool overlap. Expand only when the measured value justifies more scope.

## Explore

INSIDE THE PLATFORM

### Agentic traffic is exploding. Your defenses need to keep up.

*noxtica*

**Explore the platform**

**Platform**

#### What we measure.

We read four things about every visitor — the browser, the network, the device, and how the person behaves. Together they tell a real customer apart from a clever fake.

[Deep Dive](https://noxtica.com/deep-dive/)

**Capabilities**

- A clear risk read
- Catch the bots, keep the customers
- One console to run it all
- Fast enough to sit in checkout
- Private by design
- Yours to integrate
- MCP integration
- Built-in AI assistant

[→ Read the docs: full feature reference](https://noxtica.com/docs/features)

**Signals**

- **Browser intelligence**
  Is the browser real?
- **Network signals**
  Is the network safe?
- **Hardware verification**
  Is the device real?
- **Behavioral fingerprints**
  Is the user real?

[→ Read the docs: detection signals](https://noxtica.com/docs/detection-signals)

**Threats**

- **Bots & automated traffic**
  Recognize automated traffic before it reaches login, signup, or checkout.
- **Sessions that hide what they are**
  Surface deliberate evasion attempts without blocking honest privacy choices.
- **Suspicious origins**
  Identify the wholesale-fraud signal — without misfiring on remote workers.
- **Privacy users, treated fairly**
  Welcome legitimate privacy users while still catching the actors hiding among them.
- **Fake & throwaway devices**
  Verify the device is what it claims to be — not just the browser running on it.
- **Activity that doesn't behave human**
  Catch the sessions that look human on paper but don't behave like a person.

[→ Read the docs: detection categories](https://noxtica.com/docs/threat-categories)

**Use cases**

- **E-commerce & marketplaces**
  Stop fake-account rings and payment fraud at checkout while real shoppers breeze through.
- **Fintech & payments**
  Add a quiet extra check only when a payment looks off, so genuine customers never feel the friction.
- **Identity & account security**
  Block account takeovers and phishing relays before the attacker ever gets in.
- **Platforms & SaaS**
  Keep trust between users high by stopping duplicate-account and abuse rings at signup, at scale.

[→ Read the docs: full use cases](https://noxtica.com/docs/use-cases)

**Audiences**

- **For companies**
  Fraud teams, security engineers, platform PMs. The teams that pay when fraud lands and the teams that pay when real customers churn.
- **For platforms**
  Marketplaces, social networks, multi-sided platforms. Trust between users is the whole business — and stopping fake accounts at scale is your moat.
- **For people**
  End-users. The under-discussed stakeholder. The people who get false-positively challenged, blocked, or asked to solve CAPTCHAs for being on Brave.
- **For AI & agents**
  The agentic web. Verify and observe agents with Know Your Agent, run the console with a built-in AI assistant, and let your own agents read Noxtica over a read-only MCP integration.

[→ Read the docs: use cases per audience](https://noxtica.com/docs/impact-audiences)

## Impact

Evaluate without invented proof

### Measure the decision, not a demo score.

Public outcome numbers stay absent until their population, baseline, window, limitations, evidence, approval, and expiry are reviewable.

#### Agree the baseline

Define the protected interaction, current control, labeled outcomes, observation window, and costs before changing policy.

#### Measure both sides

Review confirmed unwanted activity alongside legitimate-customer interruption, challenge completion, review work, support load, errors, and unknown states.

#### Keep an accountable decision

Record the evidence available, the reason trail, the policy owner, the final customer action, and the conditions that pause or reverse the evaluation.

**Evaluation and trust resources**

- [Review integration responsibilities](https://noxtica.com/docs/getting-started/)
- [Review security scope](https://noxtica.com/security/)
- [Understand commercial scope](https://noxtica.com/pricing/)

## Capabilities

CUSTOMER OUTCOMES

### One operating view, from signal to outcome.

Explore the customer outcomes Noxtica supports, then use the reference to understand scope and eligibility.

#### Risk and decisioning

Turn browser, device, network, and behavioral evidence into a risk read your team can explain.

- [View capabilities](https://noxtica.com/capabilities/#risk-and-decisioning)
- [Read the reference](https://noxtica.com/docs/features/#risk-and-decisioning)

#### Device and browser intelligence

Recognize returning environments and inspect the evidence behind browser, device, and app posture.

- [View capabilities](https://noxtica.com/capabilities/#device-and-browser-intelligence)
- [Read the reference](https://noxtica.com/docs/features/#device-and-browser-intelligence)

#### Bot, abuse, and network defense

Combine automation, abuse, and network context so controls can respond without treating every unusual visitor as hostile.

- [View capabilities](https://noxtica.com/capabilities/#bot-abuse-and-network-defense)
- [Read the reference](https://noxtica.com/docs/features/#bot-abuse-and-network-defense)

#### Account linking and investigation

Follow relationships across devices, visits, accounts, and cases without losing the evidence for each link.

- [View capabilities](https://noxtica.com/capabilities/#account-linking-and-investigation)
- [Read the reference](https://noxtica.com/docs/features/#account-linking-and-investigation)

#### Journey and experience observability

Connect risk events to the session journey, performance, errors, and conversion context around them.

- [View capabilities](https://noxtica.com/capabilities/#journey-and-experience-observability)
- [Read the reference](https://noxtica.com/docs/features/#journey-and-experience-observability)

#### Monitoring, alerting, and reporting

Move from live investigation to scheduled oversight with dashboards, alerts, exports, reports, and status views.

- [View capabilities](https://noxtica.com/capabilities/#monitoring-alerting-and-reporting)
- [Read the reference](https://noxtica.com/docs/features/#monitoring-alerting-and-reporting)

#### Agent identity and control

Verify supported agent credentials, assess the surrounding request, and apply a policy for automated traffic.

- [View capabilities](https://noxtica.com/capabilities/#agent-identity-and-control)
- [Read the reference](https://noxtica.com/docs/features/#agent-identity-and-control)

#### AI-assisted operations

Investigate in the console or connect approved tools to tenant-scoped operational context.

- [View capabilities](https://noxtica.com/capabilities/#ai-assisted-operations)
- [Read the reference](https://noxtica.com/docs/features/#ai-assisted-operations)

#### Developer platform and integrations

Collect in web or mobile clients, verify on the server, and connect outputs to the systems your team already runs.

- [View capabilities](https://noxtica.com/capabilities/#developer-platform-and-integrations)
- [Read the reference](https://noxtica.com/docs/features/#developer-platform-and-integrations)

#### Identity verification and access

Support identity evidence, step-up checks, and workforce access controls as distinct governed layers.

- [View capabilities](https://noxtica.com/capabilities/#identity-verification-and-access)
- [Read the reference](https://noxtica.com/docs/features/#identity-verification-and-access)

#### Governance and data controls

Set collection, retention, access, and audit boundaries around sensitive operational evidence.

- [View capabilities](https://noxtica.com/capabilities/#governance-and-data-controls)
- [Read the reference](https://noxtica.com/docs/features/#governance-and-data-controls)

#### Workspace and commercial operations

Operate users, domains, usage, package limits, billing records, and support-facing account workflows in one console.

- [View capabilities](https://noxtica.com/capabilities/#workspace-and-commercial-operations)
- [Read the reference](https://noxtica.com/docs/features/#workspace-and-commercial-operations)

## Believe

PRINCIPLES

### What we believe.

Operating constraints that show up everywhere — in the SDK, in the API, in the operator console.

#### A read, not a verdict

You own the policy. We hand you the evidence.

#### Nothing you can't explain

Every decision comes with its reasons. No black box.

#### A blocked customer is the real cost

A blocked customer never comes back. We bias against that.

#### Private by design

No direct identifiers. No third-party calls. Nothing raw to leak.

## Replay capabilities

SESSION CONTEXT

### See the journey behind the signal.

Connect replay context, SDK diagnostics, and backend risk lookups without treating them as one data path. Replay starts only after its admission gates pass.

- [Read the replay setup](https://noxtica.com/docs/getting-started/#automatic-collection-recommended)
- [Browser runtime reference](https://noxtica.com/docs/browser-runtime/)
- [GitHub SDKs](https://github.com/noxtica)

Integration guide, not a live replay. Expanding details does not record.

EARLY WINDOW

#### Capture early context

Keep a bounded early replay buffer in browser memory. It is not transmitted before replay admission.

ADMISSION

#### Apply replay and privacy gates

Replay policy, legal basis, DNT/GPC, sampling, and consent must all admit recording.

DIAGNOSTICS

#### Read the browser runtime

Trace SDK collection, cache-hit, and error events in the browser.

BACKEND HANDOFF

#### Link context to risk

Save the fingerprint ID in your session or database for a server-side risk lookup.

#### What decides whether replay is admitted?

Replay payload transmission begins only after admission. Denying or disabling replay discards the early buffer; separate browser-risk collection can remain enabled.

[Read admission rules](https://noxtica.com/docs/getting-started/#automatic-collection-recommended)

#### How does the backend use context?

Use a scoped server credential to look up risk by fingerprint ID. Your backend decides what to do next.

[Read the backend integration guide](https://noxtica.com/docs/backend-integration/)

## Agent capabilities

AI, WITH GUARDRAILS

### Bring context to every investigation.

Use the signed-in operator assistant or separately enabled MCP access. These paths read approved workspace context; they do not describe every AI or automation surface.

[Explore agentic security](https://noxtica.com/docs/concepts/agentic-security/)

INSIDE THE CONSOLE

#### Built-in operator assistant

Read approved policy, domain, activity, and risk context within the signed-in operator session.

Runs server-side with the signed-in operator’s permissions.

##### Permissions and current scope

- Role-based permissions are checked on every tool call.
- Read policies, rules, domains, recent fingerprints, risk distribution, and audit logs.
- No configuration changes or traffic actions.

[Read the AI Assistant docs](https://noxtica.com/docs/concepts/ai-assistant/)

READ-ONLY CONTEXT

FOR EXTERNAL AGENTS

#### Scoped MCP integration

For an opted-in tenant, read approved policies, rules, alerts, and risk distribution through the JSON-RPC MCP server.

Access requires an operator-issued, scoped bearer token.

##### Activation and token controls

- Off by default; each tenant must opt in.
- Token scope limits reads; rate limits and audit records apply to this MCP path.
- No write tools or autonomous actions.

[Read the MCP integration docs](https://noxtica.com/docs/concepts/mcp-integration/)

[Request access details](https://noxtica.com/contact/)

## Whitepaper

WHITEPAPERS

### The thinking behind the score.

A deeper read on how Noxtica turns raw browser, network, device, and behavioral signals into a calibrated risk read your team can act on — and why we build for evidence you can explain, not black-box verdicts.

WHERE THIS FITS NOW

#### From identity evidence to interaction risk

Security, Evolved. traces the move from identity tokens to browser, network, device, and behavioral evidence. Agentic Security & Risk Intelligence carries that argument forward: the current interaction becomes the risk object, Noxtica returns an explainable read, and customer policy decides the action. The category guide also shows where supported identity and agent evidence fit, and why AI Assistant and MCP remain read-only aids rather than decision makers.

[Continue to the interaction-risk model](https://noxtica.com/risk-intelligence/)

[Read the whitepapers](https://noxtica.com/whitepapers/)

> Security, Evolved.

## CTA

Walk through one real decision

### Bring the interaction your team cannot afford to misread.

We will review the product view, relevant evidence and limits, integration responsibilities, and practical evaluation next steps.

[Request a walkthrough](https://noxtica.com/contact/?topic=walkthrough&sourcePage=%2F&campaignId=first-screen)

## Customer next steps

CONTINUE WITH THE QUESTION YOU OWN

### Move from interaction risk to use case to evidence.

Learn Noxtica’s Agentic Security & Risk Intelligence framing, inspect the evidence-to-policy handoff, compare the capacity your workflow needs, or scope one measurable evaluation.

- [Understand Agentic Security & Risk Intelligence](https://noxtica.com/risk-intelligence/)
  [See how Noxtica frames interaction evidence, explainable risk, and customer-owned policy.](https://noxtica.com/risk-intelligence/)
- [Compare pricing](https://noxtica.com/pricing/)
  [Match protected interactions, request and event usage, retention, eligible modules, and evaluation work to published capacity.](https://noxtica.com/pricing/)
- [Follow one risk read end to end](https://noxtica.com/deep-dive/)
  [Trace a policy-relevant interaction through result states, risk, confidence, reasons, customer policy, and outcome review.](https://noxtica.com/deep-dive/)
- [Scope an evaluation](https://noxtica.com/contact/?topic=walkthrough)
  [Bring one route, labeled outcomes, traffic shape, policy owner, and the business costs you want to compare.](https://noxtica.com/contact/?topic=walkthrough)

## Product availability

Every product page states how the product is offered. The labels mean:

- **Evaluation access.** Reached through an evaluation workspace. Contact the team to request access and confirm scope.
- **Controlled availability.** Provisioned per workspace after review. Contact the team to confirm eligibility and scope.
- **In development.** Being built. Nothing on a product page is a commitment on scope or timing.

## How the products connect

Browser scripts, signed requests and hosted pages feed the products. Your server, the console and your own AI agents read the results. Your policy makes the decision.

---

Source: https://noxtica.com/docs/use-cases/
Markdown: https://noxtica.com/docs/use-cases/index.md
Last updated: 2026-10-27

# Use Cases

These are implementation patterns, not customer case studies or promised results. They show where to collect, which Noxtica surfaces to use, what the customer application decides, and how to measure both abuse coverage and legitimate-user friction.

Before using any pattern, confirm the required module, tenant, domain, role, quota, client, data policy, and contract eligibility in Backoffice and with your Noxtica contact.

## Marketplaces

**The problem:** repeated accounts can manipulate reviews, rankings, referrals, promotions, inventory, or seller/buyer trust. Shared devices and networks are also normal, so a single match is not enough to establish abuse.

**When to use:** apply assessment at account creation and at the valuable action being protected, such as promotion redemption or review publication. Keeping both events lets an analyst distinguish ordinary signup volume from coordinated use of the platform.

**The signal:** a calibrated risk assessment and tenant-scoped device handle can be compared with account, journey, network, and prior-event context. Eligible linkage or cluster views can suggest related activity for review; they do not prove common ownership.

### How the signal compounds

A marketplace can review several evidence families together:

- **Automation and bots (01):** automated interaction or browser inconsistency reasons across attempts.
- **Fingerprint tampering (02):** a mismatch or manipulation reason that appears alongside other evidence.
- **Infrastructure abuse (03):** network context that raises concern but remains weak on its own.
- **Behavioral anomalies (06):** eligible interaction context that corroborates a pattern after required activation and review.
- **Account and journey context:** repeated attempts, promotion state, device familiarity, and confirmed platform outcomes from your own systems.

### Configure and use

1. Register the signup and protected-action origins in **Domains** and install the collector.
2. Send the returned device handle with the marketplace event to your backend; never expose a secret API key in the browser.
3. Review baseline distributions in **Analytics** and individual records in **Fingerprints**.
4. If entitled and legally approved, use **Compare**, linkage, investigation, tracker, or journey views for analyst triage.
5. Create a route-specific policy in shadow mode where available.
6. Label confirmed legitimate and abusive outcomes through the supported customer workflow.

### The policy

A practical starting policy allows low-risk traffic under ordinary account controls, observes medium risk, and uses a reversible step-up or moderation queue for high risk. Reserve blocking for reviewed conditions with stronger corroboration. Maintain explicit handling for shared households, managed devices, schools, libraries, VPNs, accessibility tools, and approved automation.

### Expected output

Operators receive risk, confidence, reason families, a device handle, and eligible relationship or journey context. The marketplace application receives only the fields it needs to decide whether to proceed, step up, hold publication, or queue review.

### The outcome

Measure duplicate-account confirmation, promotion or review-abuse rate, moderation yield, challenge completion, signup and publication abandonment, support contacts, appeal reversals, and unknown/error rates. The desired outcome is a better-ranked abuse queue and proportionate friction—not a guaranteed percentage reduction.

### Limitations

Shared attributes are hypotheses, device continuity can reset, and sparse or expired data reduces linkage quality. Investigation, linkage, detailed network, replay, and behavioral surfaces may require separate activation, legal basis, or consent.

---

## Financial services

**The problem:** account takeover, card-not-present abuse, scripted credential testing, and high-risk account changes require more context without turning every new device into a denial.

**When to use:** collect at login or session establishment and re-check or look up context at the protected transaction, payout, recovery, credential change, or beneficiary change.

**The signal:** device familiarity, browser consistency, network context, automation reasons, available integrity status, risk, and confidence can corroborate the institution's authentication, transaction, account, and fraud controls.

### How the signal compounds

- **Device context:** familiar, new, changed, or unavailable device history.
- **Automation/tampering context:** reasons that indicate scripted or inconsistent access.
- **Infrastructure context:** reputation and network-type evidence, interpreted with VPN and mobile-network exceptions.
- **Customer context:** transaction value, account history, authentication strength, recovery state, and your confirmed fraud labels.

A new device is common and must not be treated as proof of takeover. The value comes from combining it with the protected action and other evidence.

### Configure and use

1. Associate the device handle with the authenticated session on your trusted backend.
2. Create a narrowly scoped server key for eligible device or assessment reads.
3. Define separate policies for login, payment, recovery, and irreversible account changes.
4. Use shadow evaluation before enforcing and review distributions by client and journey.
5. Route eligible cases into your existing fraud or manual-review workflow through a supported event sink, webhook, export, or API integration.

### The policy

Keep normal authentication in force for every tier. A familiar low-risk session can follow the ordinary path. A new or elevated-risk session can require a stronger factor or review. A missing result, low confidence, or unavailable module should follow an explicit unknown path rather than being silently allowed or blocked.

### Expected output

Your backend receives the supported risk/device response; authorized operators can review reasons, timestamps, policy actions, and eligible investigation context in Backoffice. Optional mobile or hardware attestation adds corroborating integrity status on supported, entitled clients.

### The outcome

Measure confirmed fraud, review precision, step-up volume and completion, payment or recovery abandonment, customer-support contacts, reversals, latency in your actual path, and error/unknown rates. No chargeback reduction, false-positive rate, latency, or customer-friction result is guaranteed by this pattern.

### Limitations

Noxtica is not authentication, transaction authorization, sanctions screening, or a guarantee of account ownership. Device changes, browser restrictions, network mobility, third-party provider availability, and traffic drift can affect output. Mobile attestation, identity, advanced reputation, and event delivery are separately eligible capabilities.

---

## Identity-sensitive platforms

**The problem:** login links, passwordless flows, account recovery, credential enrollment, and identity-evidence journeys can be relayed, initiated on one device and completed on another, or interrupted for legitimate reasons.

**When to use:** capture context at both initiation and completion when the workflow needs continuity, and apply stronger authentication when the context changes or evidence is incomplete.

**The signal:** compare the tenant-scoped device handles and available assessment context at both points. If the identity module is included, its case or evidence status can be combined with device risk; neither should silently substitute for the other.

### How the signal compounds

- **Initiation context:** device handle, time, risk, confidence, and protected workflow state.
- **Completion context:** the same fields collected when the link or challenge is completed.
- **Continuity:** match, change, missing result, expired record, or low-confidence comparison.
- **Authentication/identity context:** your factor result or an eligible provider/case result.

A mismatch can mean relay abuse, but it can also mean a user moved from desktop to phone, changed browsers, or opened mail elsewhere. Treat it as a reason for step-up—not automatic guilt.

### Configure and use

1. Store the initiation device handle with the short-lived workflow record on your backend.
2. Collect again at completion and compare through the supported server or console surface.
3. Define an explicit expiration and unknown-device path.
4. If using identity, liveness, passkeys, recovery, mobile attestation, or review queues, confirm each sub-flow is entitled and configured for the supported client and jurisdiction.
5. Keep evidence access, retention, deletion, and appeal responsibilities in the workflow design.

### The policy

A matching, sufficiently evidenced context can proceed under normal authentication. A changed, missing, low-confidence, or elevated-risk context should receive the additional factor appropriate to the action. High-impact recovery or credential changes should not rely on device continuity alone.

### Expected output

The application can consume device comparison and risk inputs; eligible identity flows can add case state, evidence-processing or provider status, integrity context, review disposition, and audit history.

### The outcome

Measure successful legitimate completion, step-up completion, relay or takeover confirmations, recovery time, support contacts, accessibility exceptions, expiry rate, manual-review yield, and appeal reversals. The expected value is a consistent escalation path, not a promised fraud-reduction number.

### Limitations

A matching browser installation is not legal identity proof, and a mismatch is not proof of attack. Identity and liveness results are bounded by the configured provider, evidence, device, geography, and contract. Noxtica does not replace your authorization and recovery controls.

---

## AI agents and crawler access

**The problem:** site owners want to admit useful automated agents while limiting unknown, unverifiable, or disallowed automation. User-agent strings alone do not provide a durable trust decision.

**When to use:** use Know Your Agent for supported signed-agent traffic when the module is active. Use ordinary bot/risk controls for unsigned automation. Use read-only MCP only when _your own_ external agent needs scoped Noxtica context; MCP does not identify inbound crawlers.

### How the signal compounds

- **Agent verification:** supported credential verification can establish an agent identity state.
- **Tenant policy:** the verified identity can be allowed, denied, or observed by your tenant policy.
- **Route context:** different content or APIs can apply different actions.
- **Risk context:** device, network, automation, and request context can still matter after identity is verified.

### Configure and use

1. Enable the eligible Agentic Security/KYA module for the tenant.
2. Define allowed, denied, and unknown agent treatment.
3. Attach the policy to selected routes and start in observe-only mode.
4. Review verified, failed, and unknown traffic before enabling challenge or block actions.
5. If connecting your own agent over MCP, mint a separate scoped, rate-limited token and review its audit history.

### The policy

Separate identity from authorization. A verified agent can still be denied on a sensitive route; an unknown agent can remain observable rather than automatically blocked. Apply payment or crawl-monetization workflows only if separately offered and contracted.

### Expected output

KYA provides verified, unverified, allowed, denied, or unknown agent context plus the resulting customer policy action and audit record. MCP provides scoped read-only responses about eligible Noxtica state.

### The outcome

Measure wanted-agent success, unknown and failed-verification volume, content/API load, blocked unwanted automation, policy exceptions, support requests from agent owners, and route-specific errors. The expected value is explicit machine-traffic governance, not proof of an agent's benign intent.

### Limitations

Agent verification proves the supported credential check, not who ultimately controls the software or whether a request is safe. Protocol and agent support vary. KYA, MCP, enforcement, and crawl-commercialization capabilities have separate eligibility and configuration boundaries.

---

## Account takeover evaluation

Evaluate login and account-recovery decisions with a synthetic interaction before you change a live policy. Account takeover is a hypothesis to evaluate: ordinary customer behavior can create the same surface patterns as abuse, and a familiar environment does not prove the account is safe. One unusual signal is not proof of compromise.

Your application marks the consequential interaction. Noxtica returns the supported assessment context and the evidence state available for that interaction. Your authentication, recovery, and authorization controls remain responsible for the decision. For the wider pattern around payments and account changes, see [Financial services](https://noxtica.com/docs/use-cases/#financial-services).

### Login and recovery workflow

A login or recovery attempt can look unfamiliar for many reasons. Keep the action, the evidence state, and your application policy separate so you can review and reverse the result.

1. **Mark the consequential interaction.** Identify whether your application is evaluating a login or an account-recovery attempt. Attach the permitted server-side context that decision needs, and nothing more. Input: a bounded login or recovery event.
2. **Inspect what is known and what is not.** Read the assessment, its reasons, and the availability of contributing evidence together. Missing or failed evidence stays visible instead of becoming a reassuring result. Output: assessment context with evidence state.
3. **Apply your recovery and access policy.** Your application decides whether to continue, ask for an additional check, send the interaction to review, or stop it. The Noxtica result is an input, not authorization on its own. Decision: owned and recorded by your application.

### Evidence states for login and recovery

Absence is not the same as safety. Your evaluation must preserve the difference between an observed input, an input that was not supplied, and a check that could not complete.

| State | What it means | What you do |
| --- | --- | --- |
| Evidence present | A supported input contributed context. | Review which evidence was available, why it contributed, and whether your application has enough context to apply its chosen policy. |
| Evidence missing | An expected input was not supplied. | Treat the gap as unknown. Do not turn an omitted, blocked, or uncollected input into a low-risk signal. |
| Evidence unavailable | A check could not produce a result. | Keep timeout, unsupported, and processing-failure paths distinct so your application can use an explicit fallback. |

The server-side result states follow the same rule; see [Backend integration](https://noxtica.com/docs/backend-integration/#handle-transport-before-risk).

### Benign explanations for unfamiliar logins

Suspicious context still needs an explanation. These explanations are plausible and benign:

- A customer signs in from a replacement device, a newly installed browser, or after clearing local data.
- Travel, mobile routing, a corporate network, or a privacy service changes the apparent network context.
- A legitimate customer starts recovery after losing access to a device or password manager.
- Accessibility, privacy, or browser settings prevent an otherwise expected input from being collected.

### What cannot be inferred about an account

- A valid password or familiar device does not prove that the person is the account owner.
- A new device, network change, or automated pattern does not by itself prove compromise.
- Missing or unavailable evidence does not mean low risk and must not be displayed as safe.
- Risk context does not replace authentication, multi-factor checks, authorization, or a secure recovery process.

### Access and recovery policy

Your application owns access and recovery policy. Define the allow, additional-check, review, and stop paths in your own policy. Keep the fallback explicit when evidence is missing or unavailable, and preserve a route for legitimate customers to complete recovery.

### Implementation boundary for login and recovery

This guide does not promise a deployment mode, response time, or automatic enforcement. Scope the evaluation around the current reviewed integration and the data your application is permitted to process. [Backend integration](https://noxtica.com/docs/backend-integration/) covers the server-side lookup.

1. Verify the interaction result on the server before it can influence an access or recovery decision.
2. Limit collection to disclosed and permitted inputs; document purpose, access, retention, deletion, and unavailable behavior.
3. Define timeout, error, missing-evidence, and unsupported-client fallbacks before you observe representative traffic.
4. Keep policy changes reversible and require application-owner approval before you add customer friction.

### Evaluation plan for login and recovery

Measure abuse and legitimate recovery together. Start with a bounded login or recovery journey and outcomes your team can verify. The goal is an evaluation plan, not a promised reduction.

1. Confirmed unauthorized-access outcomes among interactions with a known final disposition.
2. Legitimate login and recovery completion, including additional-check abandonment and support escalation.
3. Review volume and time for cases that remain uncertain after you inspect the available evidence.
4. Coverage of missing, unavailable, timeout, and unknown-outcome paths rather than silently dropping them.

Define labels, observation window, population, simultaneous policy changes, and stop conditions before you interpret the evaluation. Page visits or form submissions are not product-effect evidence.

---

## Signup abuse evaluation

Evaluate repeated signup and promotion abuse with a synthetic account-creation or promotion-eligibility interaction before you change a live rule. Related-looking activity can guide investigation; it does not prove one person or one intent. Shared context does not prove a shared actor.

Your application marks the signup or promotion decision. Noxtica returns the supported assessment context and the evidence state available for that interaction. Your application remains responsible for account creation, promotion eligibility, and any additional check. For marketplace-style repeated accounts, see [Marketplaces](https://noxtica.com/docs/use-cases/#marketplaces).

### Signup and eligibility workflow

A repeated or related signup can be abusive, accidental, or expected. Evaluate the interaction in context before an application rule changes account access or promotion eligibility.

1. **Mark the signup decision.** Identify whether your application is evaluating account creation, a referral, a trial, or promotion eligibility. Attach the permitted context that rule needs, and nothing more. Input: a bounded signup or eligibility event.
2. **Inspect evidence and uncertainty.** Read the assessment, the contributing reasons, and the evidence availability together. Similarity can identify a question for review without becoming a claim about identity or intent. Output: assessment context with evidence state.
3. **Apply your account and promotion rules.** Your application decides whether to continue, ask for an additional check, limit an incentive, queue review, or stop the attempt. The policy and the customer-remedy path remain yours. Decision: owned and recorded by your application.

### Evidence states for signup

Repeated-account evaluation is especially sensitive to missing context. Keep gaps visible before you compare activity, and preserve what was observed, what was not supplied, and what could not be evaluated.

| State | What it means | What you do |
| --- | --- | --- |
| Evidence present | A supported input contributed context. | Review the available context and its reason before an account or incentive rule treats the interaction differently. |
| Evidence missing | An expected input was not supplied. | Do not treat an absent attribute as proof that the signup is isolated, related, legitimate, or abusive. |
| Evidence unavailable | A check could not produce a result. | Keep unsupported, timeout, and processing-failure paths distinct so the signup flow can use a reviewed fallback. |

### Benign explanations for related signups

Signup and promotion policy can affect legitimate customers at the start of a relationship. Review these plausible benign explanations and your recovery paths before you add friction or deny eligibility.

- People in one household, classroom, workplace, or public venue share a device or network legitimately.
- A customer retries after a form, email, payment, or verification step fails to complete.
- Corporate routing, mobile carriers, privacy services, and accessibility tools make unrelated signups look similar.
- A promotion legitimately permits separate people, teams, or accounts under terms your application defines.

### What cannot be inferred about related signups

- Matching or related attributes do not prove that two accounts belong to the same person.
- Automation context does not by itself prove harmful intent or a promotion-policy violation.
- Missing or unavailable evidence does not prove that a signup is isolated or legitimate.
- Risk context does not replace account verification, promotion terms, appeals, or customer support.

### Account and promotion policy

Your application owns account and promotion eligibility. Define which repeated activities are permitted, which require an additional check, and how a legitimate customer can correct or appeal a decision. Noxtica context does not create the promotion rule or identify a person on its own.

### Implementation boundary for signup

This guide does not promise identity certainty, automatic blocking, response time, or a deployment mode. Scope the evaluation around current reviewed integration surfaces and your published account and promotion terms.

1. Verify the interaction result on the server before it can influence account creation or incentive eligibility.
2. Limit collection to disclosed and permitted inputs; document purpose, access, retention, deletion, and unavailable behavior.
3. Define retry, duplicate, shared-environment, timeout, error, and unsupported-client handling before you change policy.
4. Start with observation and reversible review paths; application owners approve any rule that adds friction or denial.

### Evaluation plan for signup

Measure policy violations and legitimate completion together. Start with one bounded signup or promotion rule and outcomes your team can verify. The goal is to understand tradeoffs, not promise a result.

1. Confirmed account or promotion-policy violations among interactions with a known final disposition.
2. Legitimate signup completion, additional-check abandonment, appeals, and support escalation.
3. Review volume and time for possible related activity that remains uncertain after inspection.
4. Coverage of shared-environment, retry, missing, unavailable, and unknown-outcome paths.

Define the policy, labels, observation window, population, simultaneous changes, and stop conditions before you interpret the evaluation. Page visits or form submissions are not product-effect evidence.

---

## Pattern: when to block, when to challenge

Across these use cases, use the same decision sequence rather than a universal threshold:

1. **Is a valid result available?** Handle missing, expired, errored, or unsupported output explicitly.
2. **How confident is it?** Limited evidence should move the action toward defer, ordinary controls, or reversible step-up.
3. **Which reasons agree?** One network, privacy, new-device, or behavior reason is rarely enough for a consequential decision.
4. **What is the route's value and reversibility?** Reading content, redeeming a promotion, moving funds, and changing credentials need different policy.
5. **What customer safeguard exists?** Provide an accessible challenge, manual review, appeal, or recovery path.
6. **What does your shadow and labeled traffic show?** Promote only after reviewing both abuse coverage and legitimate-user friction.

A common starting map is low/minimal → allow under normal controls, medium → observe or low-friction step-up, high → challenge/hold/review, and critical → strong challenge or block under a reviewed rule. It is an example, not a default promise.

## Production readiness checklist

- Required account, tenant, domain, role, module, client, quota, and contract eligibility confirmed.
- Exact collection, optional-signal, consent/legal-basis, retention, redaction, and destination settings reviewed.
- Browser result and trusted backend lookup/error paths implemented without exposing secret keys.
- Unknown, low-confidence, provider-down, quota, and rate-limit behavior documented.
- Shadow results compared with confirmed outcomes and customer-friction measures.
- Support, appeal, recovery, rollback, and policy ownership assigned.
- Alerts, exports, event sinks, and investigations limited to necessary data and authorized recipients.

## Related reading

- [Customer capability reference](https://noxtica.com/docs/features/) — how, outputs, eligibility, and limits for each family.
- [Threat categories](https://noxtica.com/docs/threat-categories/) — public reason families used in these patterns.
- [Why calibration, not verdicts](https://noxtica.com/docs/why-calibration/) — design the risk/confidence policy.
- [Engineering principles](https://noxtica.com/docs/principles/) — review the operating constraints before enforcement.
- [Backend integration](https://noxtica.com/docs/backend-integration/) — trusted lookups and error handling.

---

Source: https://noxtica.com/docs/faq/
Markdown: https://noxtica.com/docs/faq/index.md
Last updated: 2026-09-11

# Frequently Asked Questions

These answers focus on what an integrator can observe and control. For deployment eligibility, contractual terms, or a capability not shown in your account, use the [contact page](https://noxtica.com/contact/).

## Does this work with Tor?

Tor and other anonymizing networks can be assessed, but the available evidence and confidence can differ from an ordinary browser path. Network context is one input; it should not become an automatic block by itself.

If your service is designed for people who rely on Tor, define that operating requirement before you evaluate a policy. Run in observation mode, compare outcomes on your own traffic, and choose a route-specific response. See [Privacy-browser handling](https://noxtica.com/docs/threat-categories/#04-privacy-browser-handling).

## What about privacy-focused browsers — Brave, LibreWolf, Tor?

The collector is designed to continue when browser capabilities or storage are restricted. A hardened browser may yield reduced evidence, a different confidence level, a suppressed browser verdict, or no fresh assessment if scripts or network requests are blocked.

Keep those states distinct from low risk. Do not challenge or block solely because a visitor uses a privacy-focused browser. Evaluate the scored evidence and your business context, and maintain a usable fallback when collection cannot run.

## How much does it add to my page?

The collector loads asynchronously, and the cache-respecting path avoids a full assessment on every eligible visit. The optional session-replay head helper is synchronous because it covers the earliest part of the page; omit it when replay is not part of your integration.

Measure the exact deployment on your pages. Compare before and after in your normal performance tooling, confirm `fromCache` on repeat visits, and inspect the Network panel for blocked or repeated requests. Asset size and assessment work can change across releases, so do not build a performance budget from a stale documentation number.

## Do we need to run a backend?

You need a backend for trusted application decisions. The browser collector can return a `fingerprintId` and, when not suppressed, coarse score fields. Your backend uses a secret `sk_...` API key to retrieve the tenant-scoped device record and combines it with your own account, authentication, or transaction context.

Keep secret keys off the browser. A browser result is useful for UI state and diagnostics, but high-impact allow, step-up, or block decisions belong on your server. Follow [Backend Integration](https://noxtica.com/docs/backend-integration/).

## Are you compliant with privacy regulation?

Compliance depends on your use case, jurisdiction, configuration, contract, disclosures, retention, and consent or other lawful basis. This integration guide cannot make that determination for you.

Before production use:

- review the current [Privacy Policy](https://noxtica.com/privacy/) and [Subprocessors](https://noxtica.com/subprocessors/);
- confirm the data and deployment terms applicable to your account;
- involve your privacy or legal owner in replay and behavioral-capture decisions;
- connect optional capture to the consent or lawful-basis workflow your organization approves; and
- verify denial, deletion, and retention behavior required by your own policy.

The base device assessment, session replay, and optional behavioral features are separate capabilities. Enabling one does not imply consent for another.

## What's your false-positive rate?

There is no responsible universal number for your traffic and policy. Your rate depends on the population, protected operation, threshold, confidence requirement, labels, and what you count as a false positive.

Measure on your own traffic before enforcement:

1. calculate the proposed action in observation mode;
2. join it with confirmed customer or abuse outcomes from your system;
3. segment by protected route and relevant customer cohorts;
4. review cases that would have created customer friction; and
5. promote only a threshold and fallback policy your team accepts.

Use authenticated event and export views available to your API scopes, the operator console, and eligible session replay for investigation. See [Evaluation checkpoints](https://noxtica.com/docs/integration-flow/#evaluation-checkpoints).

## What happens if your service is down?

Treat a script load failure, request timeout, network error, HTTP `5xx`, or rejected SDK promise as **unavailable**. An unavailable result has no fresh score and must not be converted to `0`, `minimal`, or `low`.

Choose the fallback per operation. A read-only page may continue, while a password reset or high-value transaction may require step-up verification or review. Keep your fallback independent of the Noxtica response path, set an application deadline, avoid tight retries, and record enough request context to investigate. Current service information is available at [status.noxtica.com](https://status.noxtica.com).

Suppressed is different from unavailable: a suppressed browser result indicates that assessment completed but browser-visible numeric verdict fields were withheld. Use its `fingerprintId` for an authenticated backend lookup.

## Can I run this on-prem?

Deployment models and on-premises eligibility are account- and contract-specific. Do not plan an on-premises or disconnected rollout from a generic documentation statement; confirm the supported package, update path, operating responsibilities, data boundary, and capability set for your account through [contact](https://noxtica.com/contact/).

When evaluating that model, assign ownership for updates, monitoring, capacity, key management, retention, incident response, and calibration review. Also confirm which browser, server, operator, replay, and export functions are included. A self-managed deployment changes who operates the service; it does not remove the need for an unavailable-result policy.

## How do you handle embedded widgets and frames?

Collection can run in an embedded frame when browser policy, sandbox permissions, origin registration, and network policy allow it. Some browser capabilities can be reduced in an embedded context.

Treat the frame context as context, not as an automatic risk decision. Test the real host and embed origins, register the correct origin, and verify postMessage or application handoff behavior you own. If collection is blocked or reduced, use the same unknown or unavailable policy as any other constrained browser path.

## What does the collector send over the network?

The browser loads the public collector asset and contacts the configured collector origin for the policy and collection requests required by the integration. Your backend separately calls authenticated Server API endpoints. If eligible session replay is enabled and admitted by policy and consent, it creates additional replay traffic; it is not part of the base result alone.

Confirm the exact behavior in the browser Network panel for your configuration. Filter by `collect.noxtica.com` or your provisioned collector origin, exercise scored, suppressed, denied-consent, cache-hit, and error paths, and compare the observed requests with your privacy and security review. Do not assume an async-only, replay-enabled, and self-managed deployment have identical network behavior.

## Can I customize the risk thresholds?

Your application owns the mapping from a scored risk record to allow, observe, step-up, or block. Operator controls available to your account may also support per-domain or per-surface policy.

Start in observation mode. Compare proposed actions with real outcomes, set confidence requirements, and define suppressed, missing, and unavailable handling separately. Change one policy boundary at a time and retain a rollback path. See [Browser Security](https://noxtica.com/docs/concepts/browser-security/) and [Integration Flow](https://noxtica.com/docs/integration-flow/#4-customer-policy).

## What's the difference between Noxtica and a CAPTCHA?

A CAPTCHA is an interaction that asks a visitor to complete a challenge. Noxtica provides a risk read your policy can use before deciding whether additional verification is appropriate.

They can be complementary: allow the normal journey when the scored evidence and your other controls support it, use a CAPTCHA or another step-up for elevated or unknown cases, and reserve denial for reviewed cases. Do not treat a CAPTCHA pass or a low Noxtica score as identity proof on its own.

## Result States and Safe Handling

Model the integration as explicit states:

| State       | What you observed                                                                           | Safe interpretation                                                        |
| ----------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| Scored      | Score, risk level, and confidence are present.                                              | Apply the policy reviewed for that operation.                              |
| Suppressed  | Assessment completed, but browser numeric fields are absent and a coarse status is present. | Risk is unknown in browser code; perform the authenticated backend lookup. |
| Cached      | `fromCache` is true.                                                                        | This is a freshness marker, not a risk tier.                               |
| Unknown     | Backend lookup returns `404` or no current record.                                          | Apply your new or missing-device policy.                                   |
| Unavailable | Timeout, network failure, SDK rejection, `429`, or `5xx`.                                   | Apply the operation's availability fallback.                               |
| Error       | Configuration or integration failure such as origin, key, scope, or CSP.                    | Fix the integration; never classify it as low risk.                        |

Only a scored state belongs in a numeric threshold comparison.

## Technical reference

The public contract is the supported SDK methods, browser events, result fields, and authenticated API responses. Internal detector names, runtime files, key identifiers, and weighting mechanisms are not integration contracts.

### Tor handling and application policy

The current public SDK contract does not require a Tor-specific client option. Use the scored record, confidence, public reason information available to your server, and your route policy. If an older example names an undocumented Tor option, do not copy it into a new integration.

### Network classification lists

Authenticated scoring can include infrastructure and anonymization context. Treat that context as one category of evidence. Availability or classification can change, and an unavailable source should reduce what you know rather than silently prove low risk.

### Result integrity and key handling

The SDK manages browser result integrity under its supported verification mode. Keep the default required posture unless your security review approves a change. Do not pin an undocumented signing-key identifier or parse an internal token format.

For a trusted application decision, use `fingerprintId` with `GET /v1/device/:deviceId` from your backend. Keep the `sk_...` key in a server-side secret manager.

### Bundle size

Measure the public asset or package version you deploy. The loader is asynchronous; additional work depends on the current policy, browser capability, and optional features. A pinned deployment must update its asset URL and published integrity value together.

### False-positive evaluation basis

A useful evaluation set comes from your own labeled outcomes and preserves the route, policy version, risk state, score when present, confidence, proposed action, final action, and outcome. Include suppressed, unknown, and unavailable cases; excluding them makes the policy look safer than the customer experience is.

### Service-degradation contract

The application contract should not depend on a fabricated neutral score. Use a discriminated state instead:

```javascript
{ state: 'scored', score, riskLevel, confidence }
{ state: 'suppressed', fingerprintId, status }
{ state: 'unknown', reason: 'device_not_found' }
{ state: 'unavailable', reason: 'timeout_or_error' }
```

Only `scored` enters a numeric threshold. Define the other actions per protected operation and test them without Noxtica being reachable.

### Headless and automation tells

Automation evidence contributes to the risk read. Detailed server and operator views are the appropriate place to investigate it; do not expose detector-specific reasons in browser messages or write policy against undocumented codes. See [Detection Signals](https://noxtica.com/docs/detection-signals/#how-a-signal-becomes-a-decision).

### Iframes and reduced browser evidence

Embedded contexts can restrict storage, browser APIs, and network access. Register the actual origin, test the sandbox attributes used by the host, and treat reduced evidence as reduced confidence—not as automatic abuse and not as a clean result.

### Network payload

During integration, use the Network panel to inventory the requests produced by your chosen path:

- public script and policy requests;
- collection submission or cache-hit behavior;
- optional replay requests after admission; and
- authenticated backend API calls, which should never appear in the browser.

Repeat the inventory with consent denied, storage unavailable, CSP restrictions, and your collector origin unreachable.

## Related reading

- [Getting Started](https://noxtica.com/docs/getting-started/#automatic-collection-recommended) — supported installation and consent qualifications.
- [Browser Runtime](https://noxtica.com/docs/browser-runtime/) — collection lifecycle, replay states, and troubleshooting.
- [Backend Integration](https://noxtica.com/docs/backend-integration/) — authenticated lookup and server-side policy.
- [Integration Flow](https://noxtica.com/docs/integration-flow/#evaluation-checkpoints) — the observe-first rollout.
- [Features Reference](https://noxtica.com/docs/features/) — customer operations and capability outputs.
- [Threat Categories](https://noxtica.com/docs/threat-categories/) — public risk categories and privacy-browser handling.

---

Source: https://noxtica.com/docs/pricing/
Markdown: https://noxtica.com/docs/pricing/index.md
Last updated: 2026-10-08

# Pricing Reference

This page is the reference version of the explanatory text on the pricing page. Live plan allowances and prices are published on the [pricing page](https://noxtica.com/pricing/); this page carries no price or quota figures.

## Plans

PRICING

### Plan from approved catalog facts.

Compare approved plan allowances, annual commitments, and month-to-month alternatives. Request a walkthrough for qualification and contract-specific terms.

### Starter

planning fit: one defined workflow and its operating assumptions

Common starting point

[Request a walkthrough for Starter](https://noxtica.com/contact/?plan=starter&billingPeriod=annual&sourcePage=/pricing/&campaignId=pricing-estimator)

### Growth

planning fit: a broader evaluated traffic and evidence scope

[Request a walkthrough for Growth](https://noxtica.com/contact/?plan=growth&billingPeriod=annual&sourcePage=/pricing/&campaignId=pricing-estimator)

### Scale

planning fit: multiple workflows with larger published allowances

[Request a walkthrough for Scale](https://noxtica.com/contact/?plan=scale&billingPeriod=annual&sourcePage=/pricing/&campaignId=pricing-estimator)

### Professional

planning fit: higher published capacity needs

[Request a walkthrough for Professional](https://noxtica.com/contact/?plan=professional&billingPeriod=annual&sourcePage=/pricing/&campaignId=pricing-estimator)

### Enterprise

planning fit: contract-defined limits, support, and service scope

- Contract-defined AI Assistant credit allowance
- Custom collector requests per month
- Custom ingestion requests per month
- Custom events per month
- Custom-day risk-evidence retention
- Custom domains

[Discuss contract scope](https://noxtica.com/contact/?plan=enterprise&billingPeriod=annual&sourcePage=/pricing/&campaignId=pricing-estimator)

### AI Assistant credits

**About AI Assistant credits**

The catalog lists a monthly plan allowance. Additional whole packs are team-provisioned and are not a self-service charge.

### Plan card allowance labels

- AI Assistant credits per month
- collector requests per month
- ingestion requests per month
- Score API calls per month
- KYC verifications included per month
- events per month
- domains

## Billing

Public catalog amounts are fixed in USD and are informational list prices that may change. Taxes, payment method, renewal, cancellation, refunds, and proration are governed by the Noxtica [Terms of Service](https://noxtica.com/terms/) (Fees, Billing and Payment section) and any applicable Order Form.

**Billing period**

- Annual
- Monthly

Billed month to month

## Estimator

ILLUSTRATIVE ESTIMATE

### Build a catalog-based estimate.

This planning aid separates the base commitment, team-provisioned capacity, and catalog-listed module usage. It is not a quote, checkout, or charge.

**Base plan**

- Starter
- Growth
- Scale
- Professional

**Billing period**

- Annual
- Monthly

- Expected collector requests per month
- Expected events per month
- Required risk-evidence retention (days)
- Domains

**Optional capacity and module assumptions**

- Advanced IP reputation requests per month

Public rules for cache hits, retries, failures, bot traffic, and duplicate submissions are not approved; estimates assume each attempt may count.

Calculate illustrative estimate

[I need help estimating](https://noxtica.com/contact/?topic=walkthrough&plan=starter&billingPeriod=annual&sourcePage=/pricing/&campaignId=pricing-estimator)

### Synthetic illustrative bill

Starter · annual base · one AI-credit pack · module usage

- Annual base commitment
- Base monthly equivalent
- Illustrative initial charge

Assumptions: every attempt may count; whole AI-credit packs round up; the plan's share of the listed module allowance applies before the per-request rate.

### Usage definitions and boundaries

- **Collector request**
  One collector /client/token issuance counted on the monthly collector-request axis.
- **Event**
  One event submission counted on the monthly event axis.
- **Ingestion request**
- **Score API call**
- **Cache hits, retries, failures, bots, duplicates**
  Public rules are not approved; estimates assume each attempt may count.
- **Capacity block**
  A whole team-provisioned pack. Partial needs round up; unused-capacity treatment is confirmed before activation.
- **Module allowance and over-limit behavior**

Definitions that state catalog figures are published on the [pricing page](https://noxtica.com/pricing/).

## Comparison

CATALOG COMPARISON

### Allowances and commercial boundaries.

Catalog-derived comparison of Noxtica plans by included units, Score API calls, KYC verifications, free-allowance share, risk-evidence retention, domains, support scope, and service-level boundary.

**Dimension**

- Events per month
- Collector requests per month
- Ingestion requests per month
- Score API calls per month
- AI Assistant credits per month
- Included KYC verifications per month
- Share of listed module and KYC free allowances
- Domains
- Retention by data class

| Dimension | Starter | Growth | Scale | Professional | Enterprise |
| --- | --- | --- | --- | --- | --- |
| Human support | English-language contact; response time confirmed during qualification | English-language contact; response time confirmed during qualification | English-language contact; response time confirmed during qualification | English-language contact; response time confirmed during qualification | English-language contact; response time confirmed during qualification |
| Public SLA | Not publicly committed | Not publicly committed | Not publicly committed | Not publicly committed | Contract only |

Enterprise column: **Custom** for events, collector requests, ingestion requests, AI Assistant credits, and domains; **Contract-defined** for retention by data class.

Retention unit: days (risk evidence).

## Add-ons

TEAM-PROVISIONED CAPACITY

### One approved whole-block add-on.

The approved projection currently lists one whole-block AI-credit add-on. Request it through the team; it is not a recurring usage charge or self-service purchase.

### Additional AI credits

A stated-price whole pack, provisioned by the team. Unused-capacity treatment and contract timing are confirmed before activation.

[Ask about this add-on →](https://noxtica.com/contact/?topic=walkthrough&sourcePage=/pricing/&campaignId=pricing-estimator)

A catalog price does not activate or charge the add-on. The team confirms eligibility, timing, and contract treatment first.

One approved whole-block add-on. — ask about team-provisioned capacity

[Ask about capacity →](https://noxtica.com/contact/?topic=walkthrough&sourcePage=/pricing/&campaignId=pricing-estimator)

## KYC rate card

KYC RATE CARD

### KYC verification pricing

One rate card for every plan. Each KYC module has its own per-use price in USD, and the Full KYC bundle combines the four core checks into one price per verification.

### Full KYC bundle

A verification that runs the full bundle is billed once, as the bundle, not again per module.

### KYC module prices

- Module
- Price
- Free each month (Enterprise)

- ID Verification
- NFC Reading
- Proof of Address
- Document AI
- Passive Liveness
- Active Liveness
- AML Screening
- Ongoing AML Monitoring
- Device & IP Analysis
- Email Verification
- Company AML Screening
- Person AML (per UBO/officer)
- KYB Documents

Each plan includes its free-allowance share of every listed monthly module and KYC allowance, rounded down to a whole unit; Enterprise includes the full listed amount.

Prices are list rates in USD. The team activates modules after an eligibility review; there is no self-service checkout or automatic charge on this page.

[Ask about KYC verification →](https://noxtica.com/contact/?topic=walkthrough&sourcePage=/pricing/&campaignId=pricing-estimator)

## Metered modules

CATALOG-LISTED MODULES

### Catalog-listed metered modules

The estimate can model Advanced IP reputation after its monthly allowance. Every catalog-listed module below is illustrative; team review and activation are still required before any of them can be enabled or charged.

Each plan includes its free-allowance share of every listed monthly module and KYC allowance, rounded down to a whole unit; Enterprise includes the full listed amount.

- Age Verify
- Bank Ownership Verify
- Calibrated Score
- Number Verify (CAMARA)
- SIM Swap Check (CAMARA)
- eID Verify
- Advanced IP reputation
- **KPS Verify**
  KPS/MERNIS is the Turkish national identity registry; this axis is only meaningful for Turkey-scoped identity checks.
- **Verified Attested KYA**
  Illustrative list rate applies to every verified attestation; there is no included monthly allowance, subject to eligibility and team activation.
- KYC Reverify
- Reputation Verify
- Speech STT (Platform)
- Speech STT (BYOK)
- Speech TTS (Platform)
- Speech TTS (BYOK)

Illustrative list rate applies to AI-credit-ledger usage, subject to eligibility and team activation.

Speech usage is metered through the AI-credit ledger, not the PAYG accrual path; this list rate is a published anchor, not a separate per-unit charge.

**Coming soon**

- Attestation Verify

Coming soon

List-rate output is illustrative. There is no automatic over-limit charge, checkout, or activation on this page.

[Ask about module eligibility →](https://noxtica.com/contact/?topic=walkthrough&sourcePage=/pricing/&campaignId=pricing-estimator)

## Why teams buy

BEFORE A COMMERCIAL DECISION

### Separate known catalog facts from contract scope.

Use the projection for planning, then confirm unresolved counting rules, eligibility, support, and terms during a guided walkthrough.

#### Known base commitment

Annual totals and month-to-month alternatives are derived from integer-cent catalog inputs, not repeated in page copy.

#### Distinct charging layers

Base plan, team-provisioned capacity, and metered module usage remain separate in the estimate.

#### Unknowns stay visible

When a requirement exceeds an approved allowance without a public rate, the estimator requests review instead of inventing a precise bill.

## FAQ

COMMERCIAL QUESTIONS

### What this catalog does—and does not—settle.

The public projection supports planning. A walkthrough confirms workflow fit and contract-specific terms.

#### What does annual billing show?

The answer quotes catalog figures; see the [pricing page](https://noxtica.com/pricing/).

#### Does the estimator produce a quote?

No. It is a read-only illustrative estimate using the versioned public projection. It does not persist inputs, run checkout, activate a module, or charge anything.

#### What happens above a plan allowance?

Score API calls above the included amount are billed as metered usage at the listed Calibrated score rate; ingestion requests are counted, not blocked. For other allowances there is no general automatic-overage promise: the estimator identifies requirements without an approved public rate and directs them to team review.

#### Are support response times or service levels included?

Human support is English-language. Response times, package scope, and any service-level commitment are confirmed during qualification or in the applicable contract.

#### How are retries, failures, bots, and duplicate submissions counted?

Those public counting rules are not yet approved. The estimator states the conservative assumption that each attempt may count and does not present the result as an exact invoice.

#### How is KYC verification priced?

Through the KYC rate card on this page: the Full KYC bundle has one price per verification with a monthly free allowance, and every other module has its own per-use price. A verification that runs the full bundle is billed once, as the bundle.

#### Need a workflow-specific estimate?

[Request a walkthrough →](https://noxtica.com/contact/?topic=walkthrough&sourcePage=/pricing/&campaignId=pricing-estimator)

## Every plan includes

**COMMERCIAL BOUNDARIES**

- Plan and allowance values come from the versioned public projection
- English-language human contact; response time is confirmed during qualification
- No self-service checkout, automatic module activation, or automatic over-limit charge
- Taxes, renewal, cancellation, refunds, proration, and service levels are governed by the Noxtica Terms of Service (Fees, Billing and Payment section) and any applicable Order Form; list prices are informational and may change

## Customer value

SCOPE BEFORE SPEND

### Buy capacity for a risk workflow you can define.

Published plans provide defined capacity. The commercial fit depends on the interactions you will protect, the traffic and history you will use, which eligible modules the evaluation requires, and the policy and review work your team will own.

### Build the purchase case from scope, usage, and evidence

USE CASE

#### Scope the interaction and its owner.

Start with one budgeted problem—account takeover, signup abuse, checkout risk, unwanted automation, or a sensitive account change. Name the team that owns the final policy and the outcome source it trusts.

USAGE

#### Size what the workflow will actually consume.

Bring protected domains, API requests, event submissions, expected peaks, retention needs, and operator access. These inputs connect published capacity to your operating model more reliably than company size.

EVALUATION

#### Define the evidence and acceptance criteria.

Confirm module, browser, consent, tenant, and policy eligibility, then compare risk, confidence, reasons, unknown states, and proposed actions against labeled traffic before enforcement.

OPERATING COST

#### Count the work and friction the policy creates.

Track challenges, completion and abandonment, human-review volume, reason usefulness, support contacts, appeals, and rollback conditions alongside the unwanted activity you find.

### Compare spend by job, not by category label

Identity, perimeter control, and analytics budgets may already solve part of the problem. Compare overlap at the exact route and decision you plan to evaluate before adding scope.

#### Identity-only lookup

Fund recognition or authentication there when that is the required outcome. Add interaction risk only when policy must evaluate the current action using more than a successful match.

#### Perimeter and bot controls

Keep the enforcement and traffic coverage that already work. Price Noxtica against the specific evidence or route-level decision gap it is expected to fill.

#### Analytics and replay tooling

Fund investigation and experience analysis there. Treat a live risk read, customer-owned policy, and explainable outcome record as separate requirements when your workflow needs them.

COMMERCIAL FIT

THE PURCHASE

#### Capacity, scope, and an operating fit.

Plans vary by published capacity and service dimensions. Additional capacity and separately eligible modules are distinct choices; use the comparison above for the current catalogue.

CONTACT FIRST

#### Every plan starts with a scope conversation.

There is no self-serve checkout. Bring your protected interaction, usage estimate, required evidence, and evaluation criteria so the team can confirm plan and module fit before provisioning.

A POOR FIT

#### A purchase with no owned policy or measurable outcome.

If nobody owns the decision, labels the evaluation, or measures customer friction and review cost, more signal volume alone will not establish value.

The closing next-steps block of the pricing page is the same as the one in [Platform Overview](https://noxtica.com/docs/platform-overview/#customer-next-steps).

---

Source: https://noxtica.com/docs/risk-intelligence/
Markdown: https://noxtica.com/docs/risk-intelligence/index.md
Last updated: 2026-10-27

# Agentic Security & Risk Intelligence

Noxtica uses **Agentic Security & Risk Intelligence** to describe the layer that connects available runtime and verification evidence to an explainable risk read for a specific digital interaction. Your policy decides what happens next.

**Agentic Security & Risk Intelligence is Noxtica's product framing.** This page does not present it as an established industry standard, legal classification, or proof of market leadership.

A digital interaction is a context-bound action or flow: creating an account, signing in, recovering access, checking out, changing a sensitive setting, or an agent calling a protected route.

## The unit of risk: start with the action that matters

Risk is evaluated for a moment with business meaning. The same device, identity, or agent can appear in interactions with different context and different consequences.

- **Signup.** Combine the available browser, device, network, and behavior evidence with the signup context. The resulting risk read can support normal passage, observation, or a customer-owned step-up path without treating one unusual signal as proof of abuse.
- **Login and recovery.** Use the current environment and interaction evidence alongside your own authentication and account history. Risk can inform a reversible step-up or review, but it does not replace authentication, authorization, or recovery controls.
- **Checkout.** Read browser, device, network, and behavioral evidence together, then combine it with the amount, account, payment, and fulfillment context your systems own. Your policy decides whether to continue, observe, step up, or review.
- **Agent interaction.** Where Know Your Agent is provisioned, supported cryptographic identity evidence can add context to the interaction. Verification identifies a supported claim; it does not prove intent, delegated authority, or that every requested action is safe.

## From evidence to risk to policy

Noxtica separates what can be observed, what the evidence suggests, and what your business chooses to do.

1. **Interaction evidence — observe what is available now.** Collect supported browser, network, device, and behavior evidence. Add identity, reputation, transaction, or agent evidence only when the relevant module and customer workflow provide it. Output: evidence with context and provenance.
2. **Explainable risk read — interpret the evidence together.** Noxtica returns a risk assessment with a named level, confidence, and available reasons. These fields are read together so uncertainty and contributing evidence stay visible. Output: risk, confidence, and reasons.
3. **Customer-owned policy — choose what the interaction requires.** Your application, operator, or configured policy maps the read and your business context to an action. Eligible [Browser Security](https://noxtica.com/docs/concepts/browser-security/) deployments can apply reviewed directives; the policy and fallback remain yours. Outcome: allow, observe, step up, review, or block.

One unusual characteristic is evidence. It is not identity proof, intent, fraud, or permission to act.

## Compose, do not discard

Identity, device, bot, agent, and fraud systems answer useful questions. Agentic Security & Risk Intelligence provides a shared frame for considering those answers at a specific action before policy responds. Evaluate the evidence handoff, failure states, and policy owner instead of asking one product to perform every job.

- **Identity and KYC:** verify supported claims or evidence. The result can inform an interaction without becoming a permanent trust label or replacing application authorization.
- **Device intelligence:** describe and compare the participating environment. Device continuity and integrity remain evidence about the current action, not proof of the person behind it.
- **Bot and automation controls:** classify automation and infrastructure patterns. Interaction context helps policy distinguish expected automation, unknown traffic, and corroborated abuse.
- **Agent authentication:** establish a supported signing identity where available. Route sensitivity, runtime evidence, authorization, and customer policy still determine how the action is treated.
- **Fraud and transaction systems:** contribute account, payment, loss, and outcome context, then consume the interaction read as another explainable input to the business decision.

## Current product boundary

The useful boundary is explicit: explainable interaction evidence now, customer-controlled action, and no claim of autonomous policy or automatic learning.

1. **Availability follows the deployment.** Evidence classes and product surfaces vary by browser support, plan, role, tenant provisioning, jurisdiction, consent, legal basis, and enabled integrations. Confirm the modules required for your evaluation.
2. **Enforcement follows reviewed policy.** The standard integration returns decision evidence to customer code. Optional Browser Security can execute customer-configured directives, including eligible challenge, block, or tarpit paths and shadow mode. It does not invent or autonomously change policy.
3. **AI remains operator-assisted and read-only.** The [AI Assistant](https://noxtica.com/docs/concepts/ai-assistant/) summarizes permitted console context under the signed-in operator. The opt-in [MCP](https://noxtica.com/docs/concepts/mcp-integration/) surface exposes eligible tenant-scoped reads. Neither currently changes Noxtica configuration or acts on traffic.
4. **Calibration is operator-tuned today.** Current scoring is operator-tuned rather than a self-learning model. Noxtica does not claim automatic learning from customer outcomes or self-directed threshold changes.
5. **Authentication does not prove intent.** [KYA](https://noxtica.com/docs/concepts/know-your-agent/) can verify supported agent identity evidence and compare it with tenant policy. It does not prove a request is authorized, beneficial, or safe, and unknown agents require a customer-defined fallback.
6. **Privacy controls remain part of the system.** Browser and device data can be personal data depending on law and use. Purpose, disclosure, legal basis, consent where required, retention, redaction, and domain policy remain customer responsibilities. Optional behavioral, replay, biometric, and raw-network features require their own eligibility and review.

## Three ways Noxtica is agentic today

"Agentic" gets thrown around. Here is exactly what it means at Noxtica: three capabilities that ship today, with no autonomous changes to your systems.

- **Noxtica operates the console.** A built-in AI assistant runs server-side under the operator session to read policies, rules, domains, and risk distribution for you, with per-tenant budget caps and full audit logging. See [AI Assistant](https://noxtica.com/docs/concepts/ai-assistant/).
- **Your agents read Noxtica.** An opt-in, read-only Model Context Protocol (MCP) server lets your own AI agents read policies, rules, alerts, and risk distribution over JSON-RPC, using scoped, rate-limited, audited bearer tokens you mint — read access only, never write. See [MCP Integration](https://noxtica.com/docs/concepts/mcp-integration/).
- **Noxtica governs the agentic web.** Know Your Agent (KYA) verifies and observes AI agents and bots per tenant by JWK thumbprint or Signature-Agent host, integrated with Web Bot Auth verification. Policy enforcement is on the roadmap. See [Know Your Agent](https://noxtica.com/docs/concepts/know-your-agent/).

Noxtica is building toward self-calibration and feedback loops; today operators tune policies and thresholds with full control.

## Evaluate on your traffic

A useful evaluation measures the risk read against outcomes your team can verify. It also tests unavailable states, customer friction, and the policy review path — not only successful collection.

1. Choose one consequential journey and define the decision, fallback, and owner.
2. Instrument scored, suppressed, missing, and unavailable result paths.
3. Observe representative traffic before changing the customer experience.
4. Join proposed actions with outcomes your team can verify, including false positives.
5. Review thresholds by surface, introduce reversible step-up first, and promote policy gradually.

## How this maps to the rest of the documentation

The "Agentic Security & Risk Intelligence" frame above is the product story that connects the following implementation-level docs. Start here, then go deeper on the piece you need:

| I need to... | Read |
| --- | --- |
| See the exact browser → server → policy flow | [Integration Flow](https://noxtica.com/docs/integration-flow/) |
| Understand what each evidence layer contributes | [Detection Signals](https://noxtica.com/docs/detection-signals/) |
| Interpret the public reason families | [Threat Categories](https://noxtica.com/docs/threat-categories/) |
| Turn risk and confidence into policy | [Why Calibration, Not Verdicts](https://noxtica.com/docs/why-calibration/) |
| Apply this to a specific journey | [Use Cases](https://noxtica.com/docs/use-cases/) |
| See the impact per audience (companies, platforms, people, AI & agents) | [Impact by Audience](https://noxtica.com/docs/impact-audiences/) |
| Review every customer capability family | [Customer Capability Reference](https://noxtica.com/docs/features/) |
| Review Noxtica's own security and trust evidence | [Security and Trust Evidence](https://noxtica.com/docs/security/) |

## Who it fits

A risk read suits journeys where the cost of being wrong differs. [The unit of risk](https://noxtica.com/docs/risk-intelligence/#the-unit-of-risk-start-with-the-action-that-matters) walks through signup, login, checkout, and agent interactions, and [Why calibration, not verdicts](https://noxtica.com/docs/why-calibration/#configure-policy-by-surface) lists what to configure per surface. [Evaluate on your traffic](https://noxtica.com/docs/risk-intelligence/#evaluate-on-your-traffic) covers comparing what a policy did, or would have done, with confirmed outcomes before you change enforcement.

- **Abuse queue triage.** Use reasons to prioritize reviews, protect expensive routes, and allow expected automation without loosening policy for everyone.

## How teams connect

Scoring uses the same browser script and authenticated server lookup as [Device Intelligence](https://noxtica.com/docs/concepts/know-your-device/#how-teams-connect). Evaluation access is required. Three surfaces expose the read:

- **Browser script.** The page callback exposes the read to your page code.
- **Authenticated server lookup.** Your backend reads the current assessment with a server-held credential.
- **Operator console.** Operators review distributions, reason categories, and calibration views. Navigation follows operator role and tenant scope.

[Detection signals](https://noxtica.com/docs/detection-signals/#expected-outputs-by-customer-surface) lists the fields each surface returns. [Integration flow](https://noxtica.com/docs/integration-flow/) and [Backend integration](https://noxtica.com/docs/backend-integration/) cover the steps.

## Limits

Plan for these boundaries before you set a threshold. [Current product boundary](https://noxtica.com/docs/risk-intelligence/#current-product-boundary) describes how availability, enforcement, AI, calibration, and privacy controls work today.

- **Evaluation access.** Core scoring belongs to an activated web integration. Advanced calibration, metered scoring, and network reputation context depend on plan, role, and tenant configuration.
- **Enforcement is controlled.** Challenge, limit, and block actions need controlled provisioning and explicit configuration for your tenant. Detection alone does not trigger them.
- **Estimates, not facts.** A score does not prove a visitor is human, fraudulent, or safe. Output is probabilistic, and no accuracy or false-positive rate is promised. Your team makes the decision. Read the [disclaimer](https://noxtica.com/disclaimer/).
- **Missing evidence is not low risk.** Blocked scripts, privacy browsers, corporate networks, and assistive technology can hide evidence or resemble abuse. Treat unknown as unknown.

## Common questions

### Does Risk Scoring decide for me?

No. It returns evidence and a risk read, and your team chooses the action. Challenge, limit, and block actions need controlled provisioning; see [Limits](https://noxtica.com/docs/risk-intelligence/#limits).

### Can I see why an assessment scored the way it did?

Assessments carry named reasons, visible according to your role and the evidence gathered. Internal weights and detection mechanics are not published. See [The reasons are the audit trail](https://noxtica.com/docs/why-calibration/#the-reasons-are-the-audit-trail).

### Does the score learn on its own?

No. Operators tune thresholds and policies today. [Current product boundary](https://noxtica.com/docs/risk-intelligence/#current-product-boundary) has the full statement.

## Related reading

- [Integration Flow](https://noxtica.com/docs/integration-flow/) — trace one evaluation from browser collection to policy.
- [Concepts: Agentic Security](https://noxtica.com/docs/concepts/agentic-security/) — the three bounded agent workflows and their decision owners.
- [Use Cases](https://noxtica.com/docs/use-cases/) — account takeover, signup abuse, checkout, and AI-agent access patterns.
- [Engineering Principles](https://noxtica.com/docs/principles/) — the operating constraints behind these defaults.

---

Source: https://noxtica.com/docs/security/audit-log-and-exports/
Markdown: https://noxtica.com/docs/security/audit-log-and-exports/index.md
Last updated: 2026-10-27

# Audit log and data export

The audit log records administrative actions in your workspace: who did it, what changed and when. Data Export downloads browser-intelligence data as files. Both leave a trail, and exports are listed in an export history.

## What it is

Availability: Availability depends on your plan, role and the modules enabled for your organisation.

| Page | Path | Who can use it |
| --- | --- | --- |
| Audit Log | Backoffice → Administration → Audit Log | Analyst, admin and superadmin roles. Viewers and billing users cannot open it. |
| Export buttons on the Audit Log | Audit Log → **Export CSV**, **Export JSON** | Admin role, with a step-up MFA check from the last 6 hours |
| Data Export | Backoffice → Administration → Exports (page title **Data Export**) | Admin role, with a step-up check |
| Export history | Data Export → **History** tab | Admin role. No step-up check for reading the list. |

The audit log is scoped to your workspace. A workspace admin never sees another workspace's entries. When Noxtica platform staff read another workspace's audit log, that read is itself audited.

The audit log supports your own review. It does not by itself certify that you meet a regulation or a standard.

### Audit log fields

| Column | Content |
| --- | --- |
| Time | When the action was recorded. |
| User | The email of the person, or the user id if no email is stored, or **System** for an automated action. |
| Action | A label such as Login, MFA Disabled, API Key Created, Role Changed or Data Export, with a severity icon. An action without a label shows its raw name with underscores replaced by spaces. |
| Target | What the action touched, for example a user email, a domain or `audit_log`. |
| Details | Structured details for the entry. Click to expand when the details are long. |

Platform staff see an extra **Tenant** column. You do not.

Examples of what is recorded: sign-in, failed sign-in and sign-out, MFA setup, enable, disable and failed verification, user creation, disabling, enabling and role changes, password resets, API key creation and revoke, domain creation, update and site-key rotation, workspace setting changes, plan-change requests, workspace switches, membership changes, mobile attestation app registration and revoke, IP allowlist rule changes, SCIM token creation and revoke, package cancellation, and data exports. Automated billing warnings appear with the user **System** and the actor `system:wallet-balance-watch` in the details.

How long entries stay depends on your plan. Backoffice → Privacy & Legal → Data retention shows the window for the audit log as a read-only row. See [Data retention, raw IP storage and data locations](https://noxtica.com/docs/compliance/retention-and-locations/).

## Prerequisites

- Analyst role or higher to read the audit log.
- Admin role to export.
- MFA enrolled on your account, so you can pass the step-up check for exports. See [Sign-in, SSO, SCIM, MFA and IP allowlist](https://noxtica.com/docs/security/sign-in-and-access/).
- For API exports: a Server API key with the `read:export` scope. See [Authentication](https://noxtica.com/docs/api/authentication/).

## Steps

### 1. Open the audit log

Go to Backoffice → Administration → Audit Log. The subtitle shows the entry count. The list is newest first, 50 entries to a page, with **Previous** and **Next**.

### 2. Filter the entries

| Control | What it does |
| --- | --- |
| Filter by action | A grouped list: Authentication, MFA, Users, Domains, API Keys, Tenants, Plan Changes, Data and others. |
| Filter by user | One person in your workspace. |
| Search by email | Matches the user email. Press Enter or click **Search**. |
| Search target or details | Matches text in the target and in the details. Use it for actions that are not in the action list. |
| From date, To date | An inclusive range. A date alone covers the whole day. |
| **Reset filters** | Clears every filter. |

Use the saved-views menu to keep a preset of the action, user, date range and detail filters.

### 3. Read one entry

Check the Action badge for severity, the User for who acted, and the Target for what was touched. Expand **Details** to see the recorded fields.

### 4. Export the audit log

1. Set the **Action** and **User** filters you need.
2. Click **Export CSV** or **Export JSON**.
3. Complete the step-up prompt if Backoffice shows one.

The file is named `audit_log_<date>.csv` or `audit_log_<date>.json`. The JSON file is an array of entries. The export applies the Action and User filters. It does not apply the date range or the text searches.

An export returns up to 50,000 rows per request by default. Each user can export up to 100,000 rows per UTC day by default. The platform can change both limits. Every export writes a Data Export row to the audit log with the row count and the format.

### 5. Run a data export

Go to Backoffice → Administration → Exports and stay on the **New export** tab.

1. Choose the **Endpoint**:

   | Endpoint | Content |
   | --- | --- |
   | Devices | The latest fingerprint record per device: device ID, payload, risk score, risk level, flags, country, city and timestamps. |
   | Events | Every fingerprint submission: device ID, domain, payload, risk score, flags, country and timestamp. |
   | Visits | Visit events where collection was skipped: device ID, domain, country, metadata and timestamp. |
   | Scored events | Per-event verdicts as a JSONL stream: event ID, device, domain, score, attestation tier, band, confidence, reason codes and timestamp. Reason codes are filled only when explainability is enabled for your organisation. |

2. Choose the **Format**: CSV or JSON. Scored events are always JSONL (NDJSON), one event per line.
3. Set **From Date** and **To Date**. Dates are read as UTC. The range can be up to 366 days and the end date cannot be in the future.
4. Optionally pick a **Domain**. Open **Show advanced filters** for Country (ISO-2), Language, Platform and a Score Min and Score Max from 0 to 100.
5. Click **Download <type> · <format>** and complete the step-up prompt if shown.

The whole file is prepared before it downloads. Large windows can take up to a minute. A success message reads **Exported N records**. **Cancel export** stops a running export and nothing is downloaded.

The payload column carries an allow-listed projection of the client payload. It is the same projection the Fingerprint detail page shows. The unprojected payload is not available to workspace admins.

Exports can contain personal data. Handle the files under your own policy. See [Privacy](https://noxtica.com/privacy/).

### 6. Review export history

Open the **History** tab. Each row shows who ran the export, the tenant scope, the surface, the window, the format and the row count. Surfaces include Fingerprints export, Events export, Visits export, Scored events export, Audit log export, Client RUM errors export, Client RUM console logs export, KYC evidence manifest and Access review export.

Export files are not kept. **Open with these filters** returns you to the page that made the export with the same filters. The export does not run again until you download it there.

### 7. Pull exports from your backend

Your backend can read the same data over the Server API with a key that has the `read:export` scope:

- `GET /v1/exports/fingerprints`
- `GET /v1/exports/events`
- `GET /v1/exports/visits`
- `GET /v1/exports/scored-events`

Parameters, paging, row caps and rate limits are in the generated reference. See [API reference](https://noxtica.com/docs/api/reference/) and [Errors](https://noxtica.com/docs/api/errors/). The routes are rate limited for each key. Over the limit you get `429` with a `Retry-After` header.

## Verify it works

- The audit log shows a **Data Export** row for your export, with you as the user and a record count in the details.
- The downloaded file opens, and the row count matches the success message.
- The **History** tab lists the export with your email, the window and the row count.
- A filtered audit log shows only the entries that match the filters, and **Reset filters** brings the full list back.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| Audit Log is missing from the menu | Your role is viewer or billing. | Ask an admin for the analyst role. |
| **No audit entries** | No entries match the filters. | Click **Reset filters**. |
| **Could not load audit log** | The read failed. | Click **Retry**. |
| **Verification cancelled — nothing was changed.** | You closed the step-up prompt, or the last MFA verification is older than 6 hours. | Export again and verify when prompted. |
| Export buttons are missing or refused | Your role is analyst. Exports need the admin role. | Ask an admin to export. |
| **Export failed: Daily export row quota exceeded** (`429`, code `EXPORT_QUOTA_EXCEEDED`) | The per-user daily row quota is used up. | Wait until the next UTC midnight. The `Retry-After` response header gives the seconds. |
| **Date range is too large. Please select a range of 366 days or less.** | The range is longer than 366 days. | Split the export into windows. |
| **To date cannot be in the future.** | The end date is after today. | Use today or an earlier date. |
| The export is smaller than expected | The per-request row cap was reached. | Narrow the window or the filters and export in parts. |
| An audit export ignores your date range | The audit export buttons apply only the Action and User filters. | Export, then filter the file. |
| The Scored events file has empty reason codes | Explainability is not enabled for your organisation. | Ask your account team. |
| History says no exports recorded | No server-side export has run for this workspace since history was recorded. | Run an export. |

## Related

- [Roles and permissions](https://noxtica.com/docs/security/roles-and-permissions/): who holds export and audit capabilities.
- [Sign-in, SSO, SCIM, MFA and IP allowlist](https://noxtica.com/docs/security/sign-in-and-access/): changes to sign-in settings appear in the audit log.
- [Data retention, raw IP storage and data locations](https://noxtica.com/docs/compliance/retention-and-locations/): retention windows and data locations.
- [API reference](https://noxtica.com/docs/api/reference/): the `/v1/exports/*` routes.
- [Billing status, grace period and reminders](https://noxtica.com/docs/billing/status-grace-reminders/): billing warnings that are written to the audit log.

---

Source: https://noxtica.com/docs/security/attestation/
Markdown: https://noxtica.com/docs/security/attestation/index.md
Last updated: 2026-10-27

# Device and app attestation

Attestation gives your backend an integrity signal from the device or app that sent a request. A workspace admin registers the mobile apps in Backoffice. Your backend then calls two Noxtica routes to verify what the device reports. Backoffice shows the results.

## What it is

Availability: Availability depends on your plan, role and the modules enabled for your organisation.

There are two attestation families. They share one Backoffice page for reading results.

| Family | What it checks | Where you work |
| --- | --- | --- |
| Mobile app attestation | Android Play Integrity and iOS App Attest results for apps you registered | Backoffice → Integrations & API → Attestation Apps, plus `POST /v1/attest/android` and `POST /v1/attest/ios` from your backend |
| Hardware Attestation (web) | The spread of CPU and GPU proof-of-work levels across your visitors, and server-verified GPU verdicts | Backoffice → Device Intelligence → Hardware Attestation |

An attestation result is a signal. Treat a missing result as unknown, not as hostile. You decide what your app does with each result.

How the mobile flow works:

1. Your backend asks Noxtica for a single-use nonce.
2. The app asks Google (Android) or Apple (iOS) for a token bound to that nonce.
3. Your backend sends the token and the nonce back to Noxtica.
4. Noxtica redeems the nonce once, checks the token, records the outcome and returns a verdict and a verification level.

The mobile SDKs for Android and iOS exist for the device side of this flow. They are private. Ask your account team for access. Do not look for them in a public package registry.

### Verdict and verification level

Every mobile response carries two values. Read both.

| Value | Meaning |
| --- | --- |
| `verdict: "pass"` | The attestation was fully verified and the platform policy was met. |
| `verdict: "fail"` | The token was not proven, was replayed, or the platform policy was not met. |
| `verdict: "error"` | Noxtica could not record the result. Retry with a new nonce. |
| `verificationLevel: "verified"` | The token was cryptographically proven. |
| `verificationLevel: "structure_only"` | iOS only. The attestation parsed and its challenge matched, but the certificate check did not complete. |
| `verificationLevel: "unverified"` | Nothing could be proven. The row is still stored. |

`pass` is returned only with `verified`. A `structure_only` or `unverified` result is never upgraded to `pass`. Handle any other verdict value as not-pass.

## Prerequisites

- A Backoffice user with the admin role. Registering or revoking an app also needs a step-up MFA check from the last 6 hours. See [Roles and permissions](https://noxtica.com/docs/security/roles-and-permissions/).
- A Server API key (`sk_prod_`) with the `read:device` scope. See [Authentication](https://noxtica.com/docs/api/authentication/).
- The mobile attestation module enabled for your organisation. Ask your account team if the Attestation Apps page or the routes do not respond for your workspace.
- Android: the package name and the SHA-256 digest of the app signing certificate.
- iOS: the bundle ID. The Apple Team ID is optional at registration and required for App Attest verification.
- For the web Hardware Attestation tabs: the Hardware Attestation add-on subscribed for your workspace and proof-of-work attestation turned on for the domain by a platform administrator. Subscribing never turns on browser compute by itself.

## Steps

### 1. Register your app

Go to Backoffice → Integrations & API → Attestation Apps. The page is titled **Mobile attestation apps**. Unregistered apps are refused.

1. Choose **Platform**: Android or iOS.
2. Enter a **Display name**. It is required and can be up to 200 characters.
3. Fill the platform fields.
4. Click **Register app** and complete the step-up prompt if Backoffice asks for it.

| Platform | Field | Rule |
| --- | --- | --- |
| Android | Package name | Required. Example `com.example.app`. |
| Android | Signing certificate SHA-256 | Required. 64 hex characters. Backoffice lower-cases it. |
| iOS | Bundle ID | Required. Example `com.example.app`. |
| iOS | Team ID | Optional, up to 64 characters. Example `TEAMID123`. |

Each registered app shows an **app key**. For Android it is the package name. For iOS it is `<TeamID>.<BundleID>`, or just the bundle ID while no Team ID is set. If you register the same identity twice, Backoffice answers that an app with this identity is already registered.

The verification route uses the package name for Android. The certificate digest is stored with the registration.

If you register an iOS app without a Team ID, native RUM and replay ingestion work for that app. App Attest verification fails closed until you add the Team ID. Use **Add Team ID** on the app row, enter the ID and click **Save**. You do not register the app again. The row then shows **App Attest configured**.

To stop trusting an app, click **Revoke** on its row and confirm. Devices that use it fail verification from then on. The row is kept as revoked for audit.

### 2. Mint a nonce from your backend

Call the route for the platform. Both routes take a Server API key as a Bearer token and a JSON body.

```bash
curl -X POST https://collect.noxtica.com/v1/attest/android \
  -H "Authorization: Bearer sk_prod_your_server_key" \
  -H "Content-Type: application/json" \
  -d '{"action":"mint"}'
```

The response:

```json
{ "ok": true, "nonce": "<nonce>", "ttlSeconds": 300, "platform": "android" }
```

The nonce lives for 300 seconds and works once. You can add `"domain_id": "<your-domain-id>"` to bind the nonce to a domain. Send the same `domain_id` when you verify.

Use `https://collect.noxtica.com/v1/attest/ios` for iOS.

### 3. Get the token on the device

Send the nonce to the app. The app requests the platform token with that nonce:

- Android: a Play Integrity standard token whose request hash is the nonce.
- iOS: an App Attest attestation whose challenge is the nonce.

The mobile SDKs wrap this step. Without an SDK, use the Google and Apple client APIs directly.

### 4. Verify the token

Send the nonce and the token back through your backend.

```bash
curl -X POST https://collect.noxtica.com/v1/attest/android \
  -H "Authorization: Bearer sk_prod_your_server_key" \
  -H "Content-Type: application/json" \
  -d '{"action":"verify","nonce":"<nonce>","integrityToken":"<play-integrity-token>"}'
```

For iOS send `attestationObject` (base64) instead of `integrityToken`. If `action` is missing, the route treats the call as `verify`.

| Body field | Used for |
| --- | --- |
| `nonce` | Required. The value from step 2. |
| `integrityToken` or `token` | Required on Android. |
| `attestationObject` or `token` | Required on iOS. |
| `app_key` | Optional. Selects one of your registered apps. Required when you have more than one active app on the platform. |
| `domain_id` | Optional. Must match the mint call when you set it there. |

The response:

```json
{
  "ok": true,
  "verdict": "pass",
  "verificationLevel": "verified",
  "platform": "android",
  "attestationId": "<id>"
}
```

Limits for both routes: a body up to 32,768 bytes, `Content-Type: application/json`, and by default 10 requests per 60 seconds for each API key. Over the limit you get `429` and a `Retry-After` header.

### 5. Act on the result in your backend

| You receive | What to do |
| --- | --- |
| `pass` and `verified` | Treat the device as attested for this action. |
| `fail` and `verified` | The token was genuine but the policy was not met. Android needs a recognised app and a device that meets device integrity. |
| `fail` and `structure_only` | The attestation parsed but was not fully proven. Do not treat it as `pass`. |
| `fail` and `unverified`, no `attestationId` | The nonce was already used, expired, or bound to another platform or domain. Mint a new nonce. |
| `fail` and `unverified`, with `attestationId` | Nothing could be proven, for example the app is not registered. Open the row in Backoffice and read **Detail**. |
| `error` | Noxtica could not record the result. Mint a new nonce and retry. |

If your workspace has a webhook subscribed to `risk.flagged`, each recorded mobile result also sends one event. Its `flags` list contains `mobile_attest:<platform>`, `mobile_attest_level:<level>` and `mobile_attest_verdict:<verdict>`. See [Webhooks](https://noxtica.com/docs/api/webhooks/).

### 6. Read results in Backoffice

Go to Backoffice → Device Intelligence → Hardware Attestation → **Mobile attestations**. The tab is tenant-wide. It is not tied to a website domain.

- Use the **Platform** filter for All platforms, Android or iOS.
- Rows are newest first, 25 to a page.
- Columns: Recorded at, Platform, Verdict, Verification level, Device binding, Detail.
- **Device binding** is a short hash. The single-use nonce is never shown.
- **Detail** lists only a fixed set of non-sensitive keys: `reason`, `app_recognition_verdict`, `device_recognition_verdict`, `integrity_level`, `environment` and `error_code`.
- With fewer than 5 records in the window, the tab hides the list and says **Too few records to show**.

The tab reads the analytics copy of the ledger. Click **Refresh** if a recent result is missing.

### 7. Read the web Hardware Attestation tabs

The Hardware Attestation page has three tabs. Admins and superadmins see all three.

| Tab | What it shows |
| --- | --- |
| Distribution | How many distinct devices reached each CPU, WebGPU and WebGL2 proof-of-work level. Filters: window (1d, 7d, 30d), device class, hardware bucket, domain. |
| GPU detail | Server-verified GPU attestation: Overview, Events and Distribution sub-tabs, with tiers Hardware, Software, Suspicious, Failed and Unavailable. |
| Mobile attestations | The mobile ledger from step 6. |

Levels are not comparable between the CPU, WebGPU and WebGL2 ladders. Read each card on its own. Cells with fewer than 5 devices are hidden for privacy.

## Verify it works

- The app appears in **Attestation Apps** with the **Active** badge. An iOS app with a Team ID also shows **App Attest configured**.
- The mint call returns a `nonce` and `ttlSeconds` of 300.
- The verify call returns `ok: true`, a `verdict`, a `verificationLevel` and an `attestationId`.
- A row for that result appears in Hardware Attestation → Mobile attestations after you click **Refresh**.
- Revoke a test app and repeat the verify call. The result is now `fail` and `unverified`, and the **Detail** column shows `reason=app_not_registered`.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| `429 Rate limit exceeded` with `Retry-After` | More than the per-key limit of attest calls in the window. | Wait for `Retry-After`. Ask your account team if you need a higher limit. |
| `415` and `Content-Type must be application/json` | The request has no JSON content type. | Send `Content-Type: application/json`. |
| `413 Payload too large` | The body is over 32,768 bytes. | Send only the nonce and the token. |
| `400` and `Missing nonce / token` | A verify call without `nonce` or without the token field. | Send both fields. |
| `503 Could not mint challenge` | Noxtica could not store the nonce. | Retry the mint call. |
| `fail` and `unverified` with no `attestationId` | The nonce is already used, older than 300 seconds, or minted for another platform or `domain_id`. | Mint a new nonce and verify once. Use the same `domain_id` in both calls. |
| `Detail` shows `reason=app_not_registered` | No active registered app matches. With several active apps you also need `app_key`. | Register the app, or send `app_key`. |
| iOS response has `error: "app_attest_team_id_missing"` | The iOS app is registered without a Team ID. | Click **Add Team ID** on the app row. |
| Android `Detail` shows `reason=not_provisioned` | Google verification is not provisioned for this deployment. | Contact your account team. |
| iOS result is `structure_only` and `fail` | The certificate check did not complete or was not met. A build signed for the Apple development environment stays at this level and shows `reason=aaguid_development`. | Test with a production-environment build. Contact your account team if production builds behave the same. |
| `Too few records to show` | Fewer than 5 records in the window. | Wait for more traffic. Individual rows stay hidden below the floor. |
| `No mobile attestations` | No device has completed an attestation for this workspace yet. | Finish steps 2 to 4 for one device. |
| `Mobile attestation events could not be loaded` | The analytics read failed. | Click **Refresh**. Contact support with the time of the attempt if it continues. |
| Distribution tab says the add-on is not subscribed | The Hardware Attestation add-on is not subscribed for the workspace. | Ask your account team. Subscribing is a platform administrator action. |
| Distribution tab says proof-of-work attestation is not enabled | The add-on is subscribed but no domain in scope has proof-of-work turned on. | Ask your account team to turn it on for the domain. |

## Related

- [Roles and permissions](https://noxtica.com/docs/security/roles-and-permissions/): who can register apps and read the tabs.
- [SDK family and availability](https://noxtica.com/docs/sdk/family/): the mobile SDKs and how to get them.
- [Authentication](https://noxtica.com/docs/api/authentication/): Server API keys and scopes.
- [Webhooks](https://noxtica.com/docs/api/webhooks/): the `risk.flagged` event.
- [Audit log and data export](https://noxtica.com/docs/security/audit-log-and-exports/): registration and revoke actions are audited.

---

Source: https://noxtica.com/docs/security/roles-and-permissions/
Markdown: https://noxtica.com/docs/security/roles-and-permissions/index.md
Last updated: 2026-10-27

# Roles and permissions

Every Backoffice user has a role in each workspace they belong to. The role decides which pages open and which changes the server accepts. This page lists the roles, what each can do, and how an admin manages people.

## What it is

Availability: Availability depends on your plan, role and the modules enabled for your organisation.

### The roles

| Role | Rank | Meant for |
| --- | --- | --- |
| Viewer | 1 | Read-only dashboards, analytics and usage. |
| Analyst | 2 | Everything a viewer can do, plus investigation reads such as the audit log. No write access. |
| Admin | 3 | Workspace management: users, domains, keys, settings, exports, billing. |
| Superadmin | 4 | Noxtica platform staff. Customers cannot assign or invite this role. |
| Billing | none | Finance staff. Holds a short, fixed list of billing capabilities. Available when enabled for your organisation. |

Viewer, analyst and admin form a ladder. A higher role holds everything a lower role holds. Billing is not on the ladder. A billing user never passes a check that asks for admin or analyst. When the billing role is not enabled for your organisation, it cannot be assigned and holds no capability.

The superadmin role works across workspaces and is used for platform operations. A workspace admin cannot grant it, and SSO or SCIM never assign it.

### Step-up MFA

Some actions need a fresh MFA verification. Backoffice shows a prompt and repeats the action after you verify. A verification stays valid for 6 hours. A user who has not enrolled MFA cannot complete a step-up check. See [Sign-in, SSO, SCIM, MFA and IP allowlist](https://noxtica.com/docs/security/sign-in-and-access/).

### Capabilities by role

The table lists customer-visible capabilities. Backoffice labels are used where they exist. A cell says whether the role holds the capability. The last column says whether a change needs step-up.

| Capability | Viewer | Analyst | Admin | Billing | Step-up |
| --- | --- | --- | --- | --- | --- |
| View Dashboard | Yes | Yes | Yes | Yes | No |
| View Analytics | Yes | Yes | Yes | No | No |
| View Fingerprints list, detail and compare | Yes | Yes | Yes | No | No |
| Usage & Quotas | Yes | Yes | Yes | Yes | No |
| View KYC usage | Yes | Yes | Yes | No | No |
| SEO checks and crawl results (read) | Yes | Yes | Yes | No | No |
| Data locations (read) | Yes | Yes | Yes | No | No |
| View Audit Log | No | Yes | Yes | No | No |
| View session replay (metadata) | No | Yes | Yes | No | No |
| View Spot captures (metadata) | No | Yes | Yes | No | No |
| View KYC verifications and review queue | No | Yes | Yes | No | No |
| View agent delegations | No | Yes | Yes | No | No |
| Billing & Plan pages: Wallet, Packages & Add-ons, Invoices, Monthly Reports | No | No | Yes | Yes | No |
| Add funds, subscribe to or cancel a package | No | No | Yes | Yes | Yes |
| Request a plan change or add-on | No | No | Yes | No | No |
| Manage Domains | No | No | Yes | No | Yes |
| Manage Users | No | No | Yes | No | Yes |
| Configure API keys | No | No | Yes | No | Yes |
| Configure mobile attestation apps | No | No | Yes | No | Yes |
| Workspace settings: SSO, SAML, SCIM, IP allowlist, Require MFA, status reports | No | No | Yes | No | Yes |
| Hardware Attestation tabs | No | No | Yes | No | No |
| Export data | No | No | Yes | No | Yes |
| Data Operations | No | No | Yes | No | Yes |
| Manage enforcement rules, agent registry, sealed results | No | No | Yes | No | Yes |
| Play session replay and Spot recordings | No | No | Yes | No | Yes |
| Manage session replay policy and Spot captures | No | No | Yes | No | Yes |
| Review KYC verifications | No | No | Yes | No | Yes |
| Access sensitive KYC evidence | No | No | Yes | No | Yes |
| View calibration, resolve false-positive disputes | No | No | Yes | No | No |

Notes on the table:

- The Billing column shows the four capabilities the billing role holds: Dashboard, Usage & Quotas, the Billing & Plan read pages, and money actions. Nothing else.
- Setting the low-balance warning threshold needs the billing-management capability but no step-up check.
- Buying AI credit packs is a workspace-settings action. It needs the admin role and a step-up check. The billing role cannot do it.
- Backoffice shows a Role capabilities card on the Users page. It is a curated view of the same server rules.
- Hiding a menu item is not the control. If a viewer opens an admin page by link, the server still refuses the save.
- Platform capabilities, for example wallet grants, invoice void and reissue, PSP credentials, grace-period changes, tenant data placement and permanent data deletion, belong to superadmin. They are not part of any customer role.

## Prerequisites

- The admin role to manage users. You can grant roles at or below your own.
- MFA enrolled on your own account, so you can pass step-up checks.
- For the billing role: the role enabled for your organisation. Ask your account team.

## Steps

### 1. Open the Users page

Go to Backoffice → Administration → Users. The list shows Email, Role, Status, Last login and Created. Use the search box for an email, or **Download CSV** to export the list. Click **Show** on the Role capabilities card to see the table above inside Backoffice.

### 2. Add a person

Click **Invite user**. When invitations are enabled for your organisation, you create a single-use link that expires after 7 days. Otherwise you create the user with a temporary password. The full flow is in [Sign-in, SSO, SCIM, MFA and IP allowlist](https://noxtica.com/docs/security/sign-in-and-access/).

The invite form offers Admin, Analyst and Viewer, and Billing when it is enabled for your organisation. You cannot offer a role above your own. Viewer is the pre-selected role.

### 3. Change a role

On the Users page, use the role selector in the person's row, or open the person and use **Role in this workspace**. Giving a higher role asks you to confirm **Grant elevated access?**. The change needs a step-up check and is audited. It ends sessions that are pinned to your workspace, so the person signs in again.

Backoffice refuses to demote, suspend, remove or disable the last active admin of a workspace. The answer is `last_admin_protected`. A Noxtica platform administrator can override this, and that override is audited.

### 4. Disable or enable a person

Use **Disable** (shown as **Revoke** in the list) in the person's row, then confirm. The person cannot sign in until you click **Enable**. Disabling ends all of their sessions. You cannot disable your own account.

If the account belongs to several workspaces, it is a **Shared account**. Account-level actions such as password reset, disabling and session control are available only when your workspace is the account's home and the account has at most one active membership. Otherwise you see only membership actions: **Suspend**, **Reactivate** and **Remove from workspace**. Those affect your workspace only.

### 5. Reset a password

Open the person and click **Reset password**. Enter a new password with at least 12 characters, an uppercase letter, a lowercase letter, a digit and a special character. The action needs a step-up check. You cannot reset your own password here.

### 6. Handle a lost second factor

A workspace admin cannot reset another user's MFA. A Noxtica platform administrator files a reset request with a reason of 5 to 500 characters, and a different platform administrator must approve it. After approval the person is signed out everywhere. At the next sign-in they see **Two-factor authentication was reset** and must enrol again. Contact Noxtica support and name the user.

A person who still has a backup code can sign in with it and then add a new authenticator.

### 7. Remove or delete a person

On the person's page, **Remove from workspace** removes only the membership. The account and its other workspaces are untouched, and the person can be invited back. **Delete user permanently** soft-deletes the account when it has no other memberships. The email is tombstoned so it can be invited again, MFA material is wiped and every session ends. Both actions need a step-up check and are audited. You cannot delete your own account.

## Verify it works

- The person appears on the Users page with the Role and the Status you set.
- Sign in as that person and open a page above their role. The page is hidden, or it opens and the server refuses the change.
- The audit log has rows for the change, such as `user_role_changed`, `user_disable`, `user_enable` or `membership_role_changed`. See [Audit log and data export](https://noxtica.com/docs/security/audit-log-and-exports/).
- The user detail page shows **Role permissions** with the capabilities inherited from the role.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| **Step-up MFA required**, or a verification prompt appears | The last MFA verification is older than 6 hours. | Enter the code from your authenticator app, then repeat the action. |
| A step-up prompt cannot be completed | You have not enrolled an authenticator, so no code exists to enter. | Enable MFA in Settings → Security. |
| `409` with `last_admin_protected` | The change would leave the workspace with no active admin. | Promote another person to admin first, then change this one. |
| **You cannot grant this role** | The role is above your own, Billing is not enabled, or Superadmin was chosen. | Choose a role at or below your own. Ask your account team about Billing. |
| Billing option missing | The billing role is not enabled for your organisation. | Ask your account team. |
| `409` with `account_managed_elsewhere`, or only membership actions shown | The account is shared with other workspaces. | Use **Suspend** or **Remove from workspace**. Password reset and disabling are managed by the account's home workspace or Noxtica support. |
| A message says superadmin users cannot be modified | You tried to change a platform account. | Contact Noxtica support. |
| A person with a Billing role sees no billing e-mails | Billing notices go to workspace admins and the nominated report contact. | Nominate the finance address as the report contact. See [Wallet, invoices and reports](https://noxtica.com/docs/billing/wallet-invoices-reports/). |
| A viewer cannot open Wallet, Packages & Add-ons, Invoices or Monthly Reports | Those pages need the admin role or the billing role. Usage & Quotas stays open to viewers. | Change the role, or use the billing role when enabled. |
| A notice says the Users list is truncated | The workspace has more users than one page shows. | Narrow the list with the search box. |

## Related

- [Sign-in, SSO, SCIM, MFA and IP allowlist](https://noxtica.com/docs/security/sign-in-and-access/): MFA, sessions, invitations and SSO.
- [Audit log and data export](https://noxtica.com/docs/security/audit-log-and-exports/): who can read the audit log and run exports.
- [Plans, packages and add-ons](https://noxtica.com/docs/billing/plans-and-packages/): billing pages and the billing role.
- [Backoffice guide](https://noxtica.com/docs/backoffice/overview/): navigation and the role-filtered sidebar.

---

Source: https://noxtica.com/docs/security/
Markdown: https://noxtica.com/docs/security/index.md
Last updated: 2026-09-27

# Security and Trust Evidence

Security review starts with scope. This page separates **implemented controls**, **independent assurance**, **contractual commitments**, and work that is **not publicly available**. It does not turn a policy, a provider report, or a source file into a certification.

- **Implemented control** — a bounded control or public process is described with its limitations.
- **Independent assurance** — a third party has assessed the named entity and scope. No current Noxtica report is listed below.
- **Contractual commitment** — the obligation exists only when the cited agreement and scope apply.
- **Planned / not available** — public evidence is absent, incomplete, or not approved for publication.

Inventory reviewed: **2026-09-20**. Next review due: **2026-12-20**.

## Evidence inventory

Each row names its evidence type, availability, owner, and review window. A link is shown only when a public destination exists. Every row was reviewed 2026-09-20 and is due for review by 2026-12-20.

| Subject | Status / availability / owner | Summary |
| --- | --- | --- |
| Company and operator | Contractual commitment; public evidence; Legal | The [legal notice](https://noxtica.com/legal-notice/) and [privacy policy](https://noxtica.com/privacy/) identify the operator and public contact route. They do not imply a separate security attestation. |
| Data flow | Implemented control; public evidence; Security and Privacy | The privacy policy describes website, collector, API, and account roles. The module data-scope table below narrows those statements and flags unavailable detail. |
| Data categories | Implemented control; public evidence; Privacy | Browser, network, account, contact, and voluntarily supplied content can include personal data. No universal no-PII or anonymous-data claim is made. See [module data scope](https://noxtica.com/docs/security/#module-data-scope) below. |
| Retention and deletion | Contractual commitment; public evidence; Privacy | Retention and deletion differ by data class, customer configuration, and applicable terms. A universal retention period is not published in this inventory. |
| Access and tenant controls | Planned / not available; public summary, details on request; Security and Engineering | Public material describes scoped credentials and role checks for selected surfaces. A current independent control report is not publicly available. See [Backend Integration](https://noxtica.com/docs/backend-integration/) for the current integration guidance. |
| Cryptography | Planned / not available; public summary, details on request; Security | Transport, storage, signatures, and payload protection are separate layers. Current public evidence does not authorize a universal end-to-end encryption claim. See the [cryptography boundary](https://noxtica.com/docs/security/#cryptography-boundary) below. |
| Service availability | Planned / not available; public evidence; Service Operations | The public status page reports service state. It is not, by itself, a contractual SLA or proof of an availability commitment. |
| Security incidents and vulnerability reports | Implemented control; public evidence; Security | The public `/.well-known/security.txt` file provides the maintained channel for vulnerability reports. Sales and security reports use separate routes. |
| Independent assurance | Planned / not available; no public evidence currently available; Security and Procurement | No current Noxtica certification or independent assurance report is approved for public listing. Hosting-provider attestations do not certify Noxtica. Request available procurement materials via [Contact](https://noxtica.com/contact/?topic=security). |
| Deployment and residency | Planned / not available; public evidence; Infrastructure and Privacy | [Subprocessors](https://noxtica.com/subprocessors/) are published. No universal hosting region, residency option, self-hosted mode, or deployment certification is represented here. |

## Cryptography boundary

A protocol or signature name is not evidence that every payload is encrypted between end users. Review each layer against the exact service, data class, and endpoint.

1. **Transport protection.** Network transport protects data between configured endpoints. It does not describe how data is stored or whether application payloads remain encrypted between their origin and final recipient. Status: scope and endpoints require current service evidence.
2. **Signatures and integrity.** A digital signature can support integrity and signer authenticity for signed bytes. A signature does not encrypt the signed payload. Do not present signed tokens as encrypted tokens.
3. **At-rest protection.** Storage protection must be evaluated per service, data class, key boundary, and provider. No universal at-rest statement is approved in this inventory.
4. **Payload end-to-end encryption.** Current public evidence does not authorize a Noxtica end-to-end payload-protection claim. The safe public status is not available.

## Module data scope

This summary is for evaluation, not legal advice. Confirm the enabled modules, configuration, contract, and current policy before deployment. Each module below is described across the same seven fields: inputs and sensitive-data possibility; trigger, configuration, and consent; client and server processing; storage and access; retention and deletion; external providers; and behavior when disabled or unavailable.

### Browser risk collection

- **Inputs:** browser, device, network, request, and timing signals can be personal data or become identifying when combined.
- **Trigger and consent:** collection depends on customer integration and configuration. The customer must establish notice, lawful basis, and consent where required.
- **Processing:** the browser collects supported signals; server-side services can add request and network context for a risk lookup.
- **Storage and access:** depend on the customer workspace, credentials, enabled surfaces, and current product configuration.
- **Retention:** must be confirmed for the applicable data class and customer configuration; no universal period is stated here.
- **External providers:** current infrastructure and service providers are listed in the subprocessor register.
- **When disabled or unavailable:** integrations must handle a missing or unavailable result rather than infer low risk.

### Session replay and behavioral evidence

- **Inputs:** recorded interactions, navigation, diagnostics, and session context can contain personal or sensitive content depending on the integrated page.
- **Trigger and consent:** replay starts only after tenant, domain, sampling, policy, legal-basis, DNT/GPC, and consent gates that apply to the deployment admit recording.
- **Processing:** a bounded early buffer remains in browser memory before admission; admitted replay payloads can then be sent for the replay workflow.
- **Storage and access:** recorded payload access requires an eligible session and an authorized role; browser risk collection is a separate module.
- **Retention:** follows the enabled replay configuration and applicable terms, not the browser-risk defaults.
- **External providers:** listed in the subprocessor register; the enabled deployment must be reviewed separately.
- **When disabled or unavailable:** denying or disabling replay discards the early replay buffer and does not disable separate browser-risk collection.

### Account and session linking

- **Inputs:** a fingerprint identifier can be associated with a customer-controlled session, account reference, or transaction; that association can be personal data.
- **Trigger and consent:** the customer chooses whether to create the association in its server-side integration and remains responsible for the purpose and notice.
- **Processing:** the browser obtains an identifier; the customer backend can carry it into a server-side lookup or its own session record.
- **Storage and access:** customer systems control their account or session mapping. Noxtica access remains bounded by the credential and workspace used for lookup.
- **Retention:** the customer must align its mapping retention and deletion with the relevant Noxtica data class and its own records.
- **External providers:** follows the services used for browser collection and server-side lookup.
- **When disabled or unavailable:** without the customer-created association, Noxtica evidence is not linked to a customer account by this integration path.

### Identity verification

- **Inputs:** no public, module-specific input inventory is currently approved for an identity-verification workflow.
- **Trigger, consent, processing, storage, retention:** not publicly represented.
- **External providers:** no identity-provider list is represented beyond the current general subprocessor register.
- **When disabled or unavailable:** treat the module as unavailable unless a separately reviewed product and privacy scope is supplied.

### AI assistance and MCP

- **Inputs:** approved read surfaces can include policies, rules, domains, recent risk evidence, distributions, and audit information; those records can contain personal data.
- **Trigger and consent:** the operator assistant follows the signed-in operator context. External MCP access is separately enabled and requires a scoped token and tenant opt-in.
- **Processing:** these public paths are server-side, read-only access. They do not authorize configuration changes or traffic actions.
- **Storage and access:** existing workspace access and retention still apply. Token scope does not make the underlying records anonymous.
- **Retention:** follows each underlying record type; AI access does not create one universal retention rule.
- **External providers:** confirm the current model and infrastructure provider scope for the enabled deployment against the subprocessor register.
- **When disabled or unavailable:** no agent access is provided through that path; existing product data remains governed by its module.

### Commercial, support, and walkthrough data

- **Inputs:** contact details, company information, selected interests, and voluntarily supplied message or preparation content are personal data.
- **Trigger and consent:** a visitor chooses to submit a contact, support, or walkthrough request. Marketing consent is separate where offered.
- **Processing:** the landing form sends submitted fields to the server-side contact workflow for the requested follow-up.
- **Storage and access:** authorized commercial or support operators can access accepted requests according to the active workflow and account controls.
- **Retention:** follows the current privacy policy, applicable terms, and a verified request process; no response-time promise is made here.
- **External providers:** current communications and infrastructure providers are listed in the subprocessor register.
- **When disabled or unavailable:** if the form or required service is unavailable, no successful receipt is represented and the visitor can use the published contact route.

## Review routes

- **[Privacy policy](https://noxtica.com/privacy/)** — controller and processor roles, data categories, purposes, rights, retention, and contact routes.
- **[Subprocessors](https://noxtica.com/subprocessors/)** — the current public list of third-party service providers.
- **[System status](https://status.noxtica.com)** — current service state and status history. This is not a contractual SLA.
- **`/.well-known/security.txt`** — the maintained vulnerability-reporting channel.
- **[Contact](https://noxtica.com/contact/?topic=security)** — request available procurement materials for the exact service and deployment under review.

## Related reading

- [Customer capability reference](https://noxtica.com/docs/features/#governance-and-data-controls) — governance and data-control capability family.
- [Engineering principles](https://noxtica.com/docs/principles/) — the operating constraints behind customer deployments.
- [Backend integration](https://noxtica.com/docs/backend-integration/) — scoped server credentials and trusted lookups.
- [FAQ](https://noxtica.com/docs/faq/) — compliance, outage handling, and on-prem questions.

---

Source: https://noxtica.com/docs/security/sign-in-and-access/
Markdown: https://noxtica.com/docs/security/sign-in-and-access/index.md
Last updated: 2026-10-27

# Sign-in, SSO, SCIM, MFA and IP allowlist

This page covers how people sign in to your Backoffice workspace and how an admin controls that. Personal security settings are on each person's own Settings page. Workspace rules are on Administration → Sign-in & Access.

## What it is

Availability: Availability depends on your plan, role and the modules enabled for your organisation.

| Control | Where | Who can change it |
| --- | --- | --- |
| Password, authenticator app, backup codes, security keys, own sessions | Backoffice → Administration → Settings → Security | Each signed-in user, for their own account |
| Single sign-on (OIDC), SAML 2.0, SCIM 2.0 | Backoffice → Administration → Sign-in & Access, tabs **Single sign-on**, **SAML**, **SCIM** | Admin, with a step-up check |
| IP allowlist | Sign-in & Access → **IP allowlist** | Admin, with a step-up check |
| Require MFA for all members | Sign-in & Access → **Require MFA** | Admin, with a step-up check |
| Invitations and users | Backoffice → Administration → Users | Admin, with a step-up check |

A step-up check is a fresh MFA verification from the last 6 hours. Backoffice asks for it when you save a sensitive change. See [Roles and permissions](https://noxtica.com/docs/security/roles-and-permissions/).

Some options depend on what is enabled for your organisation: security keys, SCIM and invitations. Where a section says so, Backoffice hides the option or answers that it is not enabled.

### Ways to sign in

- **Password.** Email and password, then a second factor when MFA is on for the account.
- **Second factor.** A 6-digit code from an authenticator app, or an 8-character backup code. When enabled for your organisation, a security key (WebAuthn) can be used as the second factor.
- **Single sign-on.** Type your work email on the sign-in page and choose **Continue with single sign-on**. Backoffice finds your workspace by the email domain and sends you to your identity provider.

Security keys are a second factor. They are not a password replacement, and they need authenticator-app MFA turned on beforehand. Console sign-in does not offer passwordless passkeys.

### Sessions

A Backoffice session lasts 24 hours from sign-in. There is no idle timeout and no sliding extension. After 24 hours you sign in again. The session cookie is `__Host-nox_admin_session`.

## Prerequisites

- The admin role for workspace settings (SSO, SAML, SCIM, IP allowlist, Require MFA, Users).
- MFA turned on for your own account, so you can pass step-up checks.
- For SSO or SAML: an identity provider that can reach Noxtica over HTTPS, and the email domains your team uses.
- For SCIM: SCIM enabled for your organisation. Ask your account team if the SCIM tab cannot create tokens.
- For the IP allowlist: the CIDR ranges your team signs in from, and your own current address inside one of them.

## Steps

### 1. Turn on MFA for your own account

Go to Backoffice → Settings → Security.

1. Click **Enable MFA**.
2. Scan the QR code with an authenticator app. If you cannot scan, use the secret key shown under the code.
3. Enter the 6-digit code and confirm. The setup link expires after 10 minutes.
4. Save the backup codes. You get 10 single-use codes and they are shown once. Use **Regenerate backup codes** to replace them. That stops the old codes at once.

To change phones, use **Replace authenticator**. Enter the code from the current app, then the code from the new one. Your other sessions are signed out.

To add a security key, use **Add a security key** after MFA is on. Remove every security key before you disable authenticator-app MFA.

### 2. Review and revoke your sessions

On Settings → Security, **Active sessions** lists Created, Last seen and Expires for each session. Your current one is marked **This device**. Use **Revoke** for one session or **Revoke All** for every other session. Both need a step-up check and are audited.

### 3. Require MFA for every member

Go to Administration → Sign-in & Access → **Require MFA**.

1. Switch on **Require MFA for all members**.
2. Confirm **Require MFA for everyone?** with a step-up check.

The status then reads **Required (since <date>)**. Members who have not enrolled MFA are sent to an enrolment page and must finish it before they continue. The default is not required.

### 4. Connect single sign-on (OIDC)

Go to Sign-in & Access → **Single sign-on**.

1. Enter the **Issuer URL**. It must be an `https` URL.
2. Enter the **Client ID** and the **Client secret**. The secret is write-only. Backoffice shows `•••• stored` afterwards and never shows it again.
3. Copy the **Callback / redirect URI** and register that exact value in your identity provider.
4. Add the **Allowed email domains** as bare domains, for example `example.com`.
5. Choose the **Default role for new SSO users**: Admin, Analyst or Viewer. Superadmin can never be assigned through SSO.
6. Click **Test discovery**. A success lists the resolved endpoints.
7. Switch on **Enable single sign-on** and click **Save configuration**.

Enabling needs a stored secret, an issuer, a client ID and at least one allowed domain. A user is created when they sign in through SSO for the initial time.

**Require SSO (disable password login)** blocks password sign-in for every member of the workspace. Turn it on after you have signed in through SSO yourself. If SSO is wrong, everyone can be locked out.

### 5. Connect SAML 2.0 (optional)

Go to Sign-in & Access → **SAML**.

1. Enter the **IdP entity ID**, the **IdP SSO URL** (HTTPS) and the **Pinned IdP signing certificate (PEM)**.
2. Enter the **SP entity ID**. Optionally add an SP signing certificate and a PKCS#8 SP private key. The key is encrypted at rest. A key needs its certificate.
3. Add the **Allowed email domains**. SAML cannot be enabled without at least one.
4. Use **Copy SP metadata URL** and register it at your identity provider.
5. Switch on **Enable SAML SSO** and click **Save SAML**.

### 6. Provision users with SCIM 2.0 (optional)

Go to Sign-in & Access → **SCIM**.

1. Enter a **Token name** (1 to 120 characters) and **TTL days**. The default is 365 days and the maximum is 730.
2. Click **Create token** and copy the token. It is shown once and cannot be recovered.
3. In your identity provider, set the SCIM base to `https://backoffice.noxtica.com/api/scim/v2` and use the `Users` resource. Send the token as a Bearer token.
4. Use **Revoke SCIM token** to stop a client at once.

What SCIM does in your workspace:

- It lists users with `GET`, with one filter: `userName eq "<email>"`. A page holds up to 100 users.
- It creates users with the Viewer role. Role is never read or written over SCIM. Change roles in Backoffice.
- `PATCH` with `active` false disables a user. `DELETE` soft-deletes the user.
- Creating a user whose email already has an account answers `409`. Use an invitation for that person.

### 7. Restrict console access by IP range

Go to Sign-in & Access → **IP allowlist**.

1. Enter a **CIDR range**, for example `203.0.113.0/24` or `2001:db8::/32`.
2. Add an optional **Label** (up to 80 characters), for example HQ VPN.
3. Click **Add range** and complete the step-up check.

With no rules, admins can sign in from any address. With one or more rules, sessions for your workspace are accepted from an address inside a rule and refused from every other address. The page shows **Enforced**. Removing the last rule turns enforcement off.

Backoffice refuses a rule set that would exclude your current address. The refusal says that your current IP would not be covered by the allowlist. Add a range that contains your address first. A workspace can hold up to 100 rules. Noxtica platform administrators are not subject to the allowlist.

### 8. Invite teammates

Go to Backoffice → Administration → Users and click **Invite user**.

1. Enter the **Email** and choose a **Role**. You can grant roles at or below your own. Superadmin is never offered.
2. Click **Create invite**, then **Copy link**. The link is single-use, expires after 7 days and is shown once.
3. Send the link to the person. They open it, set a password and click **Activate account**. A person who already has a Noxtica account signs in and uses **Join workspace** instead.

Under **Pending invites** you can **Resend** or **Revoke** an invite. Revoking makes the link stop working at once.

If invitations are not enabled for your organisation, the Users page offers an admin-created user with a temporary password instead. The password must be at least 12 characters with an uppercase letter, a lowercase letter, a digit and a special character.

### 9. Work in more than one workspace

An account can belong to several workspaces with a different role in each. When it does, a workspace switcher appears in the top bar. A switch checks that you are an active member, that the workspace is active and that your network passes that workspace's IP allowlist. Your workspace role changes with the switch.

## Verify it works

- Settings → Security shows **MFA is enabled on this account** and the backup codes count, for example 10 of 10 remaining.
- Sign-in & Access shows **Required (since <date>)** for Require MFA, **Enabled** for single sign-on, and **Enforced** for the IP allowlist.
- Sign out, type a work email on the sign-in page and choose **Continue with single sign-on**. You land in Backoffice with the default role you set.
- A request from an address outside the allowlist fails with **Access denied: your IP address is not in this account's allowlist.**
- A new invite shows in **Pending invites** with status Pending. After the person activates, the row leaves that list and the user appears in the Users list.
- Audit log rows exist for each change. See [Audit log and data export](https://noxtica.com/docs/security/audit-log-and-exports/).

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| **Invalid email or password.** | Wrong credentials. | Check the address and use **Forgot password?**. |
| **Account temporarily locked due to too many failed login attempts.** | 5 failed password attempts lock the account for 30 minutes. | Wait 30 minutes, then sign in again. |
| **Too many login attempts.** | Rate limit on the sign-in route. | Wait for the countdown shown on the page. |
| **Verification window expired.** | The second-factor step took too long. | Sign in again. |
| **Too many failed attempts. Please sign in again.** | Too many wrong second-factor codes. | Sign in again and enter the current code. |
| Lost your authenticator and backup codes | No second factor is available. | A backup code signs you in and asks you to add a new authenticator. Otherwise use **Forgot password** and reset two-factor if the page offers it. If it does not, contact Noxtica support. A workspace admin cannot reset another user's MFA. |
| **You signed in with a backup code** banner | A backup code was used. | Click **Add new authenticator** and confirm with the new app. |
| **Two-factor authentication was reset** banner | Your two-factor was removed, either by an approved platform-administrator reset or by a password reset that included resetting two-factor. | Click **Set up two-factor now**. The rest of Backoffice stays locked until you finish. |
| **Single sign-on could not be completed.** | The email domain is not claimed by an enabled SSO config, discovery fails, or the account has no usable membership. | Check **Allowed email domains** and run **Test discovery**. Confirm the redirect URI at the provider. |
| Everyone is locked out after **Require SSO** | SSO is misconfigured and password login is blocked. | Contact Noxtica support. A platform administrator can change the setting. |
| **Access denied: your IP address is not in this account's allowlist.** | Your address is outside every rule. | Sign in from an allowed network. Ask another admin or Noxtica support to adjust the rules. |
| **Access temporarily unavailable: IP allowlist could not be verified.** | The allowlist could not be read, so access is refused. | Try again shortly. |
| **IP allowlist is limited to 100 rules** | The rule limit is reached. | Remove rules you no longer need. |
| **That CIDR is already in the allowlist** | Duplicate rule. | Skip it. |
| Invite link: **Could not accept this invite. The link may have expired or already been used.** | The link was used, revoked, resent or older than 7 days. | Ask an admin to resend or create a new invite. |
| **Invite user** does nothing useful, or the Users page offers a temporary-password form | Invitations are not enabled for your organisation. | Use the temporary-password form, or ask your account team. |
| SCIM `404` | SCIM is not enabled for your organisation. | Ask your account team. |
| SCIM `409` on user create | The email already has an account. | Invite that person instead. |
| Switch fails: **Your network isn't allowed to access that workspace.** | The target workspace has an IP allowlist that excludes you. | Ask its admin to add your address. |
| Switch fails: **You are no longer an active member of that workspace.** | The membership was suspended or removed. | Ask an admin of that workspace. |

## Related

- [Roles and permissions](https://noxtica.com/docs/security/roles-and-permissions/): roles, step-up and the Users page.
- [Audit log and data export](https://noxtica.com/docs/security/audit-log-and-exports/): who changed sign-in settings and when.
- [Backoffice guide](https://noxtica.com/docs/backoffice/overview/): navigation and shortcuts.
- [Security and trust evidence](https://noxtica.com/docs/security/): what Noxtica publishes about its own controls.