Web SDK guide

Soliton Identity Verification

Keep the user on your page.

The Web SDK runs the hosted verification flow in a full-screen overlay iframe instead of a redirect. Your backend integration (create, link, result) is identical to the server API guide; use the helper below to prepare the link, then open it in your browser.

01

How it fits

Same verification, same one-time url; the SDK replaces the redirect hand-off with callbacks.

1

Create

Your backend calls startVerification() with your console API key and tier. The helper creates a v2 session, issues its link, and returns sessionId and url. Send only url to your page.

2

Open

Your page calls open({ url, ... }). The SDK covers the viewport with an overlay iframe pointing at your Soliton verification origin.

3

Capture

The user completes the camera challenge inside the iframe, on the Soliton verification origin. Your page never touches video or biometrics.

4

Callback

onComplete fires with the verification id only. Your backend fetches the verdict server-to-server, exactly as in redirect mode.

Choose liveness on your server

Set tier in the server helper (or checks[].configuration.liveness_tier in the raw v2 request): standard uses the camera with no sound or flashes; medium adds sound; high adds sound and light. The helper requires an explicit tier. Standard requests camera permission only; Medium and High also request microphone access.

Configure API_ORIGIN and VERIFICATION_ORIGIN (both https://soliton.id for this deployment) and your server-only API_KEY. Download the dependency-free helper into your backend project, review it, and keep it in source control. Requires Node.js 18+.

Get the server helper
# Download into YOUR backend project, review, and commit this file.
# Node.js 18+. Use your deployment's verification origin.
curl --fail "$VERIFICATION_ORIGIN/sdk/v1/soliton-server.mjs" \
  -o soliton-server.mjs
# Do not load this server module with a browser <script> tag.
Create the selected tier (server only)
// YOUR backend, Node.js 18+. Never bundle this file for the browser.
import { createVerificationClient } from "./soliton-server.mjs";

const soliton = createVerificationClient({
  apiOrigin: process.env.API_ORIGIN,
  verificationOrigin: process.env.VERIFICATION_ORIGIN,
  apiKey: process.env.API_KEY,
});

// Call inside your authenticated endpoint. user and attempt come from
// YOUR server. saveSession/saveLink are your database operations.
// Serialize requests for each attempt; reuse a saved URL if already issued.
const { sessionId, url } = await soliton.startVerification({
  userReference: user.id,
  tier: "high", // Choose on your server: standard | medium | high.
  idempotencyKey: attempt.id, // Stable for this attempt, not a new random key per retry.
  onSessionCreated: async (id) => {
    await saveSession(user.id, attempt.id, id); // Runs BEFORE link issuance.
  },
});
await saveLink(attempt.id, url); // Store securely; never put the link in logs.
// Return only { url } to your browser. Keep sessionId on your server.

The helper performs POST /api/v2/sessions, then POST /api/v2/sessions/{id}/link. Other languages can use those endpoints directly; see the raw API examples.

Retries and partial success

The helper never retries automatically. VerificationStartError exposes stage (create, persist or link), sessionId when known, status and retryAfter. Retry creation only with the same key and request after resolving the failure. Save a known session ID before continuing. Explicitly call issueVerificationLink(savedSessionId) to replace a missing or expired link; this invalidates the old link. A timeout may mean issuance already succeeded. Store the successful URL securely and serialize duplicate starts per attempt. The combined helper is not end-to-end idempotent.

All three tiers work with sandbox and production keys. The returned URL binds the choice for every capture and retake. Pass that URL to open(); there is no tier option or tier query parameter to set in the SDK. Use the updated hosted SDK from soliton.id. Create a new session if you need a different tier.

After onComplete, fetch GET /api/v2/sessions/{savedSessionId} from your backend. Match the saved user reference, environment and requested tier. Wait for a completed check and a final result in checks[].result; verdicts include pass, partial, fail and inconclusive. Policy decisions are separate from check outcomes.

02

Register your origins

Embedding is off by default.

Ask us to register the exact origin of every page that runs the SDK and directly contains its Soliton iframe (scheme + host + port, e.g. https://app.example.com) for your Soliton account. This direct-parent page does not have to be the browser's top-level page. Register its origin, not its path: https://app.example.com and https://app.example.com:8443 are different origins, while /verify is not part of an origin. Opened inside an iframe on any other origin, the browser blocks the frame: it stays blank and the SDK reports load_timeout after 30 seconds. Non-iframe opens (redirect mode) are unaffected: the same link works standalone or embedded. V2 does not currently offer a customer return-URL option.

Origins are registered per environment, so tell us which one each is for. A link is checked against the origins registered for the environment of the key that created it: your staging page can embed sk_test_ links without being able to embed sk_live_ ones.

Allow the embed in your response headers

CSP (Content Security Policy) is the browser response header that controls which sources a page may load. If the page that runs the SDK sends a restrictive CSP, merge the Soliton source into its existing directives; do not replace the rest of your policy with these minimal examples. The frame-src source is required for every SDK distribution. The script-src source is needed only when loading the classic or ESM bundle directly from your verification origin, not when your app bundles the npm package. If any document above the Soliton iframe restricts camera or microphone in Permissions-Policy, every level in a nested frame chain must allow and delegate camera access for Standard, and camera plus microphone access for Medium and High, through each intervening iframe; an upstream denial cannot be overridden lower in the chain. The SDK already adds the matching allow attribute on the iframe it creates.

Minimal Soliton sources when bundling the npm package
# Soliton example for the npm package:
Content-Security-Policy: frame-src https://soliton.id
Permissions-Policy: camera=(self "https://soliton.id"), microphone=(self "https://soliton.id")
Minimal Soliton sources when loading a hosted SDK build
# Soliton example for the classic CDN script or hosted ESM:
Content-Security-Policy: frame-src https://soliton.id; script-src https://soliton.id
Permissions-Policy: camera=(self "https://soliton.id"), microphone=(self "https://soliton.id")
  • These examples use https://soliton.id. Add a staging origin to these directives only when Soliton has supplied its exact, working staging URL; include both origins only if the same page can open both environments.
  • For local customer-page testing, send us the exact origin, including its port (for example http://localhost:3000), for registration. It does not belong in frame-src or script-src while the iframe and hosted SDK still come from the Soliton verification origin.
  • Do not add Soliton to your page's frame-ancestors. That directive controls who may frame your page; frame-src controls what your page may frame.

03

Install

No runtime dependencies, no framework requirements.

Use the hosted browser script below from this deployment. Check that an npm release supports the current API before using it. The server helper is a separate module: do not load soliton-server.mjs in the browser. Use the downloaded server module in your backend project.

npm (only when your package release supports your deployment)
npm install @soliton-id/web-sdk
Or via script tag (same API, updates with every Soliton deploy)
<script src="https://soliton.id/sdk/v1/soliton-web-sdk.js"></script>
<!-- exposes the global SolitonVerify; SolitonVerify.open({...}) -->

A hosted ESM build is also available at https://soliton.id/sdk/v1/soliton-web-sdk.esm.js.

04

Open the flow

One call: open() renders the overlay and relays the hosted page’s lifecycle to your callbacks.

Open the flow
// Load the hosted browser SDK first (see Install).
// Wire this function to your Verify button.
async function verify() {
  try {
    // YOUR authenticated backend uses startVerification() and returns { url }.
    const response = await fetch("/your-api/start-verification", { method: "POST" });
    if (!response.ok) throw new Error("Could not start verification");
    const { url } = await response.json();
    return SolitonVerify.open({
      url,
      onComplete: ({ verificationId }) => {
        // A completion signal, not a verdict. Ask YOUR backend to fetch
        // the ses_ ID it saved for this user, never the callback UUID alias.
      },
      onError: ({ code, message }) => {
        // Show recovery guidance; the overlay stays open.
      },
      onClose: () => {
        // Dismissed before completion; offer a retry.
      },
    });
  } catch {
    // Includes setup errors thrown synchronously by open().
    console.error("Could not start verification. Check setup and connection.");
  }
}
// const handle = await verify();
// handle?.close() dismisses the overlay programmatically.
  • The overlay is always full-viewport for every tier. High uses the whole screen for its light challenge; Standard and Medium keep the same layout without flashes. Do not clip the overlay into a widget.
  • The same v2 link works standalone or embedded. V2 does not accept redirect_url; embedded integrations resume through callbacks.
  • To open straight into the camera, add intro=skip to the hosted URL; see If you skip the instructions screen.
  • handle.close() dismisses the overlay programmatically and fires onClose if no terminal state was reached.

If you skip the instructions screen

By default the flow opens on Soliton’s instructions screen and the user taps Begin. Adding intro=skip to the hosted URL, embedded or as a top-level redirect, opens straight into the camera instead. If you skip it, you must:

Skip the instructions screen
const directUrl = new URL(url);
directUrl.searchParams.set("intro", "skip");
const handle = SolitonVerify.open({ url: directUrl.toString(), onComplete });
  1. Explain the check and collect biometric consent first. Before you open the link, tell the user what happens (camera, plus microphone for Medium and High) and get their express consent to the collection and use of their facial biometric data, for example with a button whose label or nearby text says so. Link our biometric privacy notice (live keys) or testing data policy (sandbox keys), which the instructions screen would otherwise show, and keep a record of each consent: the time, the text shown and the user. Skip our screen only if yours does all of this. For Medium and High, also ask users to turn their speaker volume up, which the instructions screen does.

    When you skip our screen, you collect this consent, and you are responsible for it and for keeping its record on your own systems. Sending us a copy is optional: when you create the session, you can add when the person agreed and which version of your consent text they saw. Soliton then also keeps it for at least 5 years, linked to the session and your user reference. Without the helper, send "consent": {"given_at": "…", "notice_version": "…"} in the POST /api/v2/sessions body.

    Send your consent record (optional)
    // YOUR backend: the same start call, plus the consent your screen collected.
    const { sessionId, url } = await soliton.startVerification({
      userReference: user.id,
      tier: "high",
      idempotencyKey: attempt.id,
      // When the person agreed, and which version of your consent text they saw.
      consent: { givenAt: attempt.consentGivenAt, noticeVersion: "your-consent-v3" },
      onSessionCreated: async (id) => { await saveSession(user.id, attempt.id, id); },
    });

    We can also set your account to require a consent record, everywhere or only where the person is located in places we agree with you (judged from their IP address; a location we cannot determine counts as one of those places). Then, if you skip our screen without sending consent, the person sees Soliton’s consent screen instead, or the check cannot start and onError reports consent_required, depending on your account’s setting.

  2. Let every iframe pass on camera, microphone and autoplay. Each iframe between the browser window and the hosted page, including yours, needs allow="camera; microphone; autoplay; fullscreen". The SDK’s own iframe already sets it.
  3. Configure your WebView if your page runs inside a native app. A WebView needs the camera and microphone grants below even without skipping; the autoplay setting is what removes the extra tap. In React Native WebView, set mediaPlaybackRequiresUserAction={false}, allowsInlineMediaPlayback and mediaCapturePermissionGrantType="grantIfSameHostElsePrompt".
iOS (WKWebView)
// iOS: the WKWebView that loads your page. Info.plist needs
// NSCameraUsageDescription and NSMicrophoneUsageDescription.
let config = WKWebViewConfiguration()
config.allowsInlineMediaPlayback = true
config.mediaTypesRequiringUserActionForPlayback = []
let webView = WKWebView(frame: .zero, configuration: config)
webView.uiDelegate = self

func webView(_ webView: WKWebView, requestMediaCapturePermissionFor origin: WKSecurityOrigin,
             initiatedByFrame frame: WKFrameInfo, type: WKMediaCaptureType,
             decisionHandler: @escaping (WKPermissionDecision) -> Void) {
  // `origin` is your top-level page; `frame` is the Soliton iframe asking.
  let asking = frame.securityOrigin
  decisionHandler(asking.protocol == "https" && asking.host == "soliton.id" ? .grant : .prompt)
}
Android (WebView)
// Android: the WebView that loads your page. Request CAMERA and RECORD_AUDIO
// at runtime first; the manifest needs both.
webView.settings.apply {
  javaScriptEnabled = true
  domStorageEnabled = true
  mediaPlaybackRequiresUserGesture = false
}
webView.webChromeClient = object : WebChromeClient() {
  override fun onPermissionRequest(request: PermissionRequest) {
    val asking = request.origin // the Soliton iframe's origin
    if (asking.scheme != "https" || asking.host != "soliton.id") return request.deny()
    request.grant(request.resources.filter {
      it == PermissionRequest.RESOURCE_VIDEO_CAPTURE || it == PermissionRequest.RESOURCE_AUDIO_CAPTURE
    }.toTypedArray())
  }
}

What users then see: Standard opens the camera with no tap. Medium and High start their sound as soon as the camera is on, with no tap, in Safari, Chrome and Firefox. In an Android WebView without mediaPlaybackRequiresUserGesture = false, which includes in-app browsers such as Instagram or Facebook on Android, the user taps Proceed once. There is no Back button to the instructions screen.

05

Callbacks and failure modes

Three callbacks cover every runtime outcome.

onComplete

Fired once, when the flow reaches a terminal state (pass OR final fail; deliberately not distinguished here). Carries only the verificationId, never a verdict. The overlay closes itself right after.

onError

A flow-level error (codes below). The overlay stays open so the hosted page can show its own error card; call handle.close() if you want it gone. The exception is load_timeout, which closes the overlay itself.

onClose

The user dismissed the flow (the X button, the hosted Cancel, or handle.close()) before completion. Not fired after onComplete.

onError codes:

link_invalid

The URL is not a live verification link: malformed token, or the verification does not exist.

link_expired

The link has expired or is no longer usable. Issue a replacement for an open session, or create a new session if the previous one has ended. Replacing a link invalidates the old one.

origin_not_allowed

The hosted page loaded, but this particular link may not be embedded on your page, for example a console test link opened inside your app. Open links your server creates with your API key.

storage_unavailable

The user's browser blocked the session storage the flow needs (fires before camera start, so no capture is lost).

link_already_used

The capture was already started from this link in another browser or on another device, or the check had already finished when this browser came back to it, so it cannot be continued here. A reload or a new tab in the same browser otherwise continues the capture. The hosted page shows a closing message and makes no further requests. Create a new session for the user. Using up the tries ends with onComplete, as after a final failed take, not with this error.

capture_failed

The capture could not be completed on this device: its last try never reached us, so there is no verdict. The hosted page shows a closing message; the check stays open and expires unfinished. Create a new session for the user.

internal

We could not prepare the verification. Check the saved session state on your server before offering an explicit retry.

load_timeout

The frame did not become ready within 30 seconds; the overlay closes and onClose follows. A frame that stayed blank almost always means your page's exact origin is not registered for the link's environment, so the browser blocked it: the browser console shows a frame-ancestors error. Send us the origin from your address bar. Otherwise it is a loading failure, never a verdict.

06

Get the verdict

Server-to-server only, exactly like redirect mode.

Server API guide

Create sessions and links, read check results, and handle retries with the v2 API.

07

Why a Soliton-hosted iframe

The capture engine never runs on your origin.

Always our origin

Anti-injection and anti-deepfake defenses update with every Soliton deploy, without you shipping anything.

Verdicts stay server-side

postMessage payloads carry only the verification id. Any machine-readable pass/fail on your page would hand fraudsters an oracle.

Messages are triple-checked

The SDK only trusts events from the hosted origin, from its own iframe’s window, carrying the protocol marker; everything else is ignored.