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.
Soliton Identity Verification
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
Same verification, same one-time url; the SDK replaces the redirect hand-off with callbacks.
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.
Your page calls open({ url, ... }). The SDK covers the viewport with an overlay iframe pointing at your Soliton verification origin.
The user completes the camera challenge inside the iframe, on the Soliton verification origin. Your page never touches video or biometrics.
onComplete fires with the verification id only. Your backend fetches the verdict server-to-server, exactly as in redirect mode.
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+.
# 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.// 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.
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
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.
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.
# 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")# 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")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.frame-ancestors. That directive controls who may frame your page; frame-src controls what your page may frame.03
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 install @soliton-id/web-sdk<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
One call: open() renders the overlay and relays the hosted page’s lifecycle to your callbacks.
// 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.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.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:
const directUrl = new URL(url);
directUrl.searchParams.set("intro", "skip");
const handle = SolitonVerify.open({ url: directUrl.toString(), onComplete });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.
// 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.
allow="camera; microphone; autoplay; fullscreen". The SDK’s own iframe already sets it.mediaPlaybackRequiresUserAction={false}, allowsInlineMediaPlayback and mediaCapturePermissionGrantType="grantIfSameHostElsePrompt".// 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: 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
Three callbacks cover every runtime outcome.
onCompleteFired 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.
onErrorA 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.
onCloseThe user dismissed the flow (the X button, the hosted Cancel, or handle.close()) before completion. Not fired after onComplete.
onError codes:
link_invalidThe URL is not a live verification link: malformed token, or the verification does not exist.
link_expiredThe 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_allowedThe 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_unavailableThe user's browser blocked the session storage the flow needs (fires before camera start, so no capture is lost).
link_already_usedThe 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_failedThe 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.
internalWe could not prepare the verification. Check the saved session state on your server before offering an explicit retry.
load_timeoutThe 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
Server-to-server only, exactly like redirect mode.
07
The capture engine never runs on your origin.
Anti-injection and anti-deepfake defenses update with every Soliton deploy, without you shipping anything.
postMessage payloads carry only the verification id. Any machine-readable pass/fail on your page would hand fraudsters an oracle.
The SDK only trusts events from the hosted origin, from its own iframe’s window, carrying the protocol marker; everything else is ignored.