Quickstart

This guide takes you from zero to your first identity risk snapshot using the headless Web SDK. Your backend signs a short-lived session with your publishable key, the browser SDK collects device and behavioral telemetry and requests the snapshot, and you read the verdict and decide what to do. Your secret key never touches the browser.

Identity Intelligence is an evidence provider — the snapshot gives you a score and a verdict, but never blocks on its own. The final decision is always yours.

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

Get your keys

From the merchant panel, create:

a publishable key (mk_live_pk_…) — safe to reference from your backend's session-init call, origin-bound, and
an Ed25519 key pair — used from your server to mint a Bearer token (at_live_…) for direct server-side analysis and queries.

The publishable key only authorises minting a session; it cannot read snapshots. See Authentication for the full model.

Sign a session on your backend

The browser never holds a key. Instead, your backend calls POST /identity/sdk/init with the publishable key and returns the result — a signed SDK session token plus an endpoint map — to the page. The call 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"
  }'

Load the SDK and analyze (browser)

Load the headless SDK from https://cdn.lunixi.com and initialise a client. Point sessionBootstrapUrl at the backend endpoint from the previous step — the SDK fetches the signed session, calls init(), then analyze() returns the snapshot. There is no UI to mount.

<script src="https://cdn.lunixi.com/lunixi-identity.min.js"></script>
<script>
  // createClient → init() → analyze()
  const client = await Lunixi.identity.init({
    sessionBootstrapUrl: '/lunixi/identity/session', // your backend from step 2
    subjectId: 'cus_8f2a9c',        // who you are scoring
    productContext: 'checkout',     // the business context
  });
 
  const snapshot = await client.analyze();
</script>

⚠️

The SDK is not fail-open — if a call fails it throws or rejects. Wrap init()/analyze() in try/catch and decide how your flow should behave when a snapshot is unavailable. The one graceful case is an oversized payload (> 48 KB), which is truncated and flagged with __sdkTruncated: true.

Read the verdict and decide

The snapshot is a flat object. Read the canonical identityRiskLevel (or the numeric riskScore) and apply your own policy.

  // ...continuing from analyze()
  switch (snapshot.identityRiskLevel) {
    case 'critical':
    case 'high':
      // your decision: step up, review, or decline
      break;
    case 'medium':
      // your decision: add friction (e.g. OTP)
      break;
    default: // 'low' | 'clean'
      // proceed
  }
 
  // Or use the raw scores + explainable surface:
  console.log(snapshot.riskScore, snapshot.confidenceScore, snapshot.reasonCodes);

What you get back

{
  "identityRiskLevel": "high",
  "identityRiskPolicyVersion": "2026-07-01",
  "riskScore": 72,
  "confidenceScore": 0.91,
  "knownDevice": true,
  "sameDeviceProbability": 0.97,
  "networkCategory": "vpn",
  "vpnDetected": true,
  "botClassification": "automation_likely",
  "reasonCodes": ["vpn_detected", "automation_likely", "new_actor_cluster"],
  "findings": [
    { "code": "vpn_detected",      "severity": "medium", "scoreDelta": 18, "source": "network" },
    { "code": "automation_likely", "severity": "high",   "scoreDelta": 26, "source": "bot" }
  ]
}

Every field is documented in The Risk Snapshot.

Next steps

Authentication — publishable keys, SDK session tokens and server-side Bearer, side by side.
Web SDK — the full client API: configure, createClient, init, analyze, track, config and events.
The Risk Snapshot — every score, signal and verdict field.
Server-side API & Queries — analyze from your backend and read past sessions.

Overview Authentication