---
title: "Web SDK API"
description: "Browser SDK endpoints and device signal collection."
collection: "api-reference"
slug: "websdk"
url: "https://naiza.ai/docs/api-reference/websdk"
markdown: "https://naiza.ai/docs/api-reference/websdk.md"
full_docs: "https://naiza.ai/docs.md"
product: "Naiza"
base_url: "https://api.naiza.ai/api/v1"
---

# Web SDK API

> Browser SDK endpoints and device signal collection.

## Table of contents

- [Deployment modes](#deployment-modes)
  - [Mode A (canonical) — Mint + Bearer + /collect (sync decision)](#mode-a-canonical-mint-bearer-collect-sync-decision)
  - [Mode B — Mint + Bearer + /websdk/signals (async queue)](#mode-b-mint-bearer-websdksignals-async-queue)
  - [Mode C (legacy / gateway-specific) — proxy /collect with x-api-key](#mode-c-legacy-gateway-specific-proxy-collect-with-x-api-key)
- [1) Mint SDK token](#1-mint-sdk-token)
- [2A) Canonical collect (/collect) — CollectSessionDto](#2a-canonical-collect-collect-collectsessiondto)
- [2B) Signals ingest (/websdk/signals) — websdk.v1 envelope](#2b-signals-ingest-websdksignals-websdkv1-envelope)
- [Validation rules](#validation-rules)
  - [Canonical /collect](#canonical-collect)
  - [/websdk/signals](#websdksignals)
- [Failure modes](#failure-modes)
- [Related](#related)

Browser ingestion uses the **`naiza-web-sdk`** UMD bundle from `sdk.naiza.ai` (or self-hosted). For installation and script-tag examples, see **Guides → Web SDK — Install & CDN**.

This page reflects the current canonical backend contract in `naiza_core`.

## Deployment modes

### Mode A (canonical) — Mint + Bearer + `/collect` (sync decision)

- `POST /api/v1/websdk/tokens` (server-to-server) with `x-api-key` returns a short-lived JWT.
- `POST /api/v1/collect` (browser-to-server) uses `Authorization: Bearer <token>`.
- Request body is `CollectSessionDto`.
- Response is the same decision shape family as `POST /api/v1/events`.

### Mode B — Mint + Bearer + `/websdk/signals` (async queue)

- `POST /api/v1/websdk/tokens` (server-to-server) with `x-api-key`.
- `POST /api/v1/websdk/signals` (browser-to-server) uses `Authorization: Bearer <token>`.
- Request body is the `websdk.v1` envelope.
- Response is queue acknowledgment (`status: queued`, `batchId`).

### Mode C (legacy / gateway-specific) — proxy `/collect` with `x-api-key`

Some deployments keep a non-canonical proxy contract where browser requests to a custom `/collect` URL expect `x-api-key`. Treat this as environment-specific compatibility mode, not the canonical `naiza_core` `/api/v1/collect` contract.

---

## 1) Mint SDK token

```http
POST /api/v1/websdk/tokens
```

Request:

```json
{
  "sdkSessionId": "sdk_01HZ9XKPQR3N8T5VWMYJ4GE7D",
  "tenantSessionId": "sess_abc123",
  "origin": "https://app.example.com",
  "flow": "checkout",
  "userExternalId": "user_789"
}
```

Response:

```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2026-04-16T10:45:00.000Z",
  "sdkSessionId": "sdk_01HZ9XKPQR3N8T5VWMYJ4GE7D"
}
```

## 2A) Canonical collect (`/collect`) — `CollectSessionDto`

```http
POST /api/v1/collect
Authorization: Bearer <short-lived-sdk-token>
Content-Type: application/json
```

Request:

```json
{
  "sessionId": "sdk_01HZ9XKPQR3N8T5VWMYJ4GE7D",
  "category": "AUTHENTICATION",
  "customerId": "user_789",
  "deviceId": "device_abc",
  "payload": {
    "flow": "checkout",
    "step": "submit"
  },
  "sdkSignals": {
    "clipboard_paste_detected": true,
    "keystroke_intervals_ms": [120, 95, 140],
    "mouse_entropy_score": 0.72
  }
}
```

Response:

```json
{
  "eventId": "evt_abc123",
  "decision": "ALLOW",
  "score": 0.14,
  "eventCategory": "AUTHENTICATION",
  "rulesEvaluated": 8
}
```

## 2B) Signals ingest (`/websdk/signals`) — `websdk.v1` envelope

```http
POST /api/v1/websdk/signals
Authorization: Bearer <short-lived-sdk-token>
```

Request:

```json
{
  "schemaVersion": "websdk.v1",
  "batchId": "01HZ9XKPQR3N8T5VWMYJ4GE7D",
  "sentAt": 1742126100000,
  "sdkSessionId": "sdk_01HZ9XKPQR3N8T5VWMYJ4GE7D",
  "tenantSessionId": "sess_abc123",
  "anonymousId": "anon_abc123",
  "identity": {
    "userExternalId": "user_789"
  },
  "page": {
    "url": "https://app.example.com/checkout",
    "referrer": "https://google.com"
  },
  "signals": {
    "mouse_move_count": 42,
    "keystroke_intervals_ms": [120, 95, 140],
    "timezone_offset": -300
  }
}
```

Response:

```json
{
  "status": "queued",
  "batchId": "01HZ9XKPQR3N8T5VWMYJ4GE7D"
}
```

---

## Validation rules

### Canonical `/collect`

- `sessionId` in request body must match the `sdkSessionId` claim in the Bearer token.
- `category` must be a valid `EventCategory` (`AUTHENTICATION`, `TRANSACTION`, `OTHER`).
- Optional object fields (`payload`, `sdkSignals`) are depth/size validated.

### `/websdk/signals`

- `sentAt` must be within +/-5 minutes of server time.
- `sdkSessionId` in body must match the authenticated token claim.
- `batchId` is treated idempotently for duplicate submissions.

---

## Failure modes

- `401`: missing/invalid/expired token or origin mismatch.
- `422`: payload validation failure, timestamp window failure, or session mismatch.
- `429`: throttled; retry with backoff.

---

## Related

- Open **Guides → Web SDK — Install & CDN** for CDN integration examples and cross-origin verification.

## Related documentation

- [API Overview](https://naiza.ai/docs/api-reference/overview.md) — Base URL, versioning, and high-level API surface.
- [Authentication](https://naiza.ai/docs/api-reference/authentication.md) — API keys, Web SDK tokens, and secure key handling.
- [Events API](https://naiza.ai/docs/api-reference/events.md) — Submit and query product events for risk evaluation.
- [Sessions API](https://naiza.ai/docs/api-reference/sessions.md) — Session grouping and timeline endpoints.
- [Error Handling](https://naiza.ai/docs/api-reference/errors.md) — Error shapes, status codes, and retry guidance.
- [Rate Limiting](https://naiza.ai/docs/api-reference/rate-limiting.md) — Quota headers and rate-limit behavior.
- [Decisions API](https://naiza.ai/docs/api-reference/decisions.md) — approve / deny / review evaluation and decision payloads (Events API uses ALLOW/REVIEW/BLOCK).
- [Lists API](https://naiza.ai/docs/api-reference/lists.md) — Allowlists, blocklists, and list membership management.

---

*Source: [https://naiza.ai/docs/api-reference/websdk](https://naiza.ai/docs/api-reference/websdk) · Full docs: [https://naiza.ai/docs.md](https://naiza.ai/docs.md)*