All documentation

Web SDK API

Browser SDK endpoints and device signal collection.

Download Markdown
GuidesAPI ReferenceCode ExamplesBest Practices

Web SDK API

Browser signals are delivered with naiza-web-sdk — load the UMD bundle from sdk.naiza.ai or self-host a downloaded release. Install and verification examples are under Guides → Web SDK — Install & CDN.

The canonical backend contract in naiza_core is Bearer-based for both /collect and /websdk/signals.

Deployment modes

Mode A (canonical) — Mint + Bearer + /collect

  • POST /api/v1/websdk/tokens uses x-api-key server-to-server.
  • POST /api/v1/collect uses Authorization: Bearer <token> from minting flow.
  • Request body is CollectSessionDto and returns sync decision response.

Mode B — Mint + Bearer + /websdk/signals

  • POST /api/v1/websdk/signals also uses Bearer token and accepts the websdk.v1 envelope.
  • Response is queue acknowledgment ({ status: "queued", batchId }).

Mode C (legacy) — proxy /collect + x-api-key

  • Some custom gateway deployments keep a proxy URL expecting x-api-key.
  • Use only when explicitly documented for that environment.

Endpoints

1) Mint SDK token

POST /api/v1/websdk/tokens

Request:

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

Response:

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

2A) Canonical collect (`/collect`)

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

Request:

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

2B) Signals ingest (`/websdk/signals`)

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

Request:

{
  "schemaVersion": "websdk.v1",
  "batchId": "01HZ9XKPQR3N8T5VWMYJ4GE7D",
  "sentAt": 1742126100000,
  "sdkSessionId": "sdk_01HZ9XKPQR3N8T5VWMYJ4GE7D",
  "signals": {
    "mouse_move_count": 42,
    "keystroke_intervals_ms": [120, 95, 140]
  }
}

Response:

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

Validation rules

  • Canonical /collect: sessionId must match token claim.
  • /websdk/signals: sentAt must be within +/-5 minutes and batchId is idempotent.

Failure modes

  • 401: missing/invalid token or origin mismatch.
  • 422: session mismatch or payload validation error.
  • 429: throttled; retry with backoff.

Related Docs