Authentication

Identity Intelligence uses two authentication paths depending on where the call originates. The browser never holds a secret; instead it runs on a short-lived, signed SDK session token minted with your publishable key. Your server uses a Bearer secret key for direct analysis and queries.

Path	Credential	Used by
Web SDK session	Publishable key (`mk_live_pk_…`) at init → signed session token	`/identity/sdk/*` (browser)
Server-side	Bearer access token (`at_live_…`)	`/identity/*` (your backend)
Public	none	`/identity/.well-known/jwks.json`, `/identity/sdk/compatibility`

Base URL for all examples: https://api-gateway.lunixi.com/api/v1.

Web SDK: publishable key → session token

The browser SDK is authenticated in two stages, and the secret key never enters the browser.

Stage 1 — mint a session (your backend). Your backend calls POST /identity/sdk/init with the publishable key in the Authorization header. The publishable key is not an SDK config field — it lives only in this server-side init call. The response is a signed SDK session token plus an endpoint map. The session is bound to allowedOrigin.

curl -X POST "https://api-gateway.lunixi.com/api/v1/identity/sdk/init" \
  -H "Authorization: PublishableKey mk_live_pk_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "allowedOrigin": "https://shop.example.com" }'

Stage 2 — call with the session token (browser). Every subsequent SDK call (analyze-sync, event, events/batch) carries the session token as Authorization: Bearer <token>. The token is only in the header — there is no token or session-proof field in the request body. If a call returns a refreshed token, the SDK rotates to it automatically.

You rarely write these calls by hand — the Web SDK manages the session and headers for you. You feed it the session from stage 1 via one of the bootstrap patterns below.

Bootstrap patterns

How the SDK obtains the stage-1 session, without ever seeing a key:

Pattern	Field	When to use
Callback	`sessionBootstrap(fn)`	The SDK calls your async function, which fetches the session from your backend and returns it. Most flexible.
URL	`sessionBootstrapUrl`	The SDK fetches the session from a backend URL you expose (a thin proxy of `POST /identity/sdk/init`). Simplest.
Pre-fetched	`sessionData`	You already fetched the session server-side (e.g. injected into the page) and hand the object straight to the SDK.

⚠️

The publishable key authorises minting a session only — it cannot read snapshots. Keep the secret key server-side. Sessions are origin-bound: allowedOrigin defaults to window.location.origin, and a token minted for one origin is refused from another.

Server-side: Bearer secret key

For backend analysis and queries, send your access token (at_live_…) as a Bearer token. The tenant is derived from the token — every call is automatically scoped to the merchant the token was minted for, and results are merchant-scoped and redacted.

curl -X POST "https://api-gateway.lunixi.com/api/v1/identity/live-sessions/analyze-sync" \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{
    "subjectType": "customer",
    "subjectId": "cus_8f2a9c",
    "productContext": "checkout"
  }'

⚠️

The secret key must never ship to a browser, a mobile app or a public repository. If it leaks, revoke it in the merchant panel and issue a new one.

Which endpoint uses which model

Endpoint group	Auth	Notes
`POST /identity/sdk/init`	Publishable key	Origin-bound; mints the session token
`POST /identity/sdk/live-sessions/analyze-sync`	Signed SDK token	Bearer session token in header
`POST /identity/sdk/live-sessions/event`, `/events/batch`	Signed SDK token	Event ingest from the browser
`POST /identity/sdk/compatibility`	Public	No auth — capability probe
`POST /identity/live-sessions/analyze`, `/analyze-sync`	Bearer secret key	Async (`traceId`) or synchronous snapshot
`POST /identity/live-sessions/event`, `/events/batch`	Bearer secret key	Server-side event ingest
`GET /identity/live-sessions*` (list, `:traceId`, timeline, related, links)	Bearer secret key	Merchant-scoped queries
`.../mobile-threat/`, `.../pos-threat/`, `/identity/mobile-apps`	Bearer secret key	Enrollment-gated surfaces
`GET /identity/.well-known/jwks.json`	Public	Verify signed identity assertions — see Assertions & JWKS

Next steps

Web SDK — the client API and every bootstrap/config field.
Server-side API & Queries — analyze and read sessions from your backend.
Assertions & JWKS — verifying a non-repudiable identity assertion.

Quickstart Web SDK