Hosted verification
Server + redirect
Your server gets a verification link. Your website sends the user to Soliton. Your server reads the result.
This guide opens a hosted page and needs no browser SDK or embedding-origin registration. To keep verification inside your app, use the Web SDK guide.
Your server · Setup
1. Add your API key
Create a sandbox key in the console. Load these values into your backend’s environment; keep the key out of browser code and source control.
API_ORIGIN=https://soliton.id
VERIFICATION_ORIGIN=https://soliton.id
API_KEY=your_console_sandbox_secretAPI_ORIGIN receives server requests. VERIFICATION_ORIGIN hosts the page your user visits. Both use https://soliton.id for this deployment.
Your server · Node.js 18+
2. Get a verification link
Add an authenticated endpoint in your app, such as POST /your-api/start-verification. Use the helper below to create a session, save its ID, and issue a link. It returns { sessionId, url }; send only { url } to your browser.
Choose your tier on the server: Standard uses camera (~2 seconds of capture); Medium adds sound (~2 seconds); High adds sound and light (~6 seconds). The example uses High.
# 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.user, attempt, saveSession and saveLink belong to your application. Save the session ID against the signed-in user before returning the URL. Keep the chosen tier, user reference and environment with that record.
Using another language? Make the two API calls directly
This replaces the helper. You do not need to run these calls again if you used startVerification().
Create the session
curl --fail -X POST "$API_ORIGIN/api/v2/sessions" \
-H "Authorization: Bearer $API_KEY" \
-H "Idempotency-Key: your-unique-check-id" \
-H "Content-Type: application/json" \
-d '{"client_reference_id":"your-user-reference","checks":[
{"type":"presence","configuration":{"liveness_tier":"high"}}
]}'Save the response’s id (ses_…) as SESSION_ID for the authenticated user. Choose a stable idempotency key per attempt; reuse it only with the same request body.
If you skip Soliton’s instructions screen (intro=skip), you collect biometric consent on your own screen first, and you are responsible for it and for keeping its record on your own systems. Sending us a copy is optional: add "consent": {"given_at": "…", "notice_version": "…"} to this body, with when the person agreed and which version of your consent text they saw. Soliton then also keeps it for at least 5 years. If we have set your account to require consent and you skip the screen without sending it, the person sees Soliton’s consent screen instead, or the check cannot start, depending on your account’s setting. See If you skip the instructions screen.
Issue its link
curl --fail -X POST "$API_ORIGIN/api/v2/sessions/$SESSION_ID/link" \
-H "Authorization: Bearer $API_KEY"Resolve the returned browser_path against VERIFICATION_ORIGIN: new URL(browser_path, verificationOrigin).href. Return that URL to your browser. Issuing a new link invalidates the previous link.
Retries and partial success
The helper makes two v2 requests. It does not retry automatically and is not end-to-end idempotent. VerificationStartError exposes stage (create, persist or link), sessionId when known, status and retryAfter.
For a create failure, retry with the same key and body after resolving the error. Persist a known session ID before recovery. For a missing or expired link, explicitly call issueVerificationLink(savedSessionId); this replaces the previous link. A timeout may mean issuance already succeeded. Store a successful URL securely and serialize duplicate starts per attempt.
Your website · Browser
3. Send the user to Soliton
Connect your Verify button to your backend endpoint, then navigate to the URL it returns. Soliton handles camera permissions and capture on the hosted page.
// YOUR website: call your own authenticated backend endpoint.
async function startVerification() {
try {
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();
window.location.assign(url);
} catch {
// Show an error and let the user retry.
}
}
// Call startVerification() when the user clicks your Verify button.After verification: the current v2 API does not automatically redirect users back to your app. Tell them to return using their browser’s Back button. Your app should check the saved session when they return; your backend can also poll while they are away.
Your server · Result
4. Read the result
Fetch the session ID your server saved for the signed-in user. Your browser should call your backend for the outcome; it never needs the Soliton API key.
# YOUR server: SESSION_ID is the ID you saved for this user.
curl --fail "$API_ORIGIN/api/v2/sessions/$SESSION_ID" \
-H "Authorization: Bearer $API_KEY"{
"id": "ses_example",
"status": "completed",
"checks": [
{
"type": "presence",
"status": "completed",
"result": {
"state": "final",
"verdict": "pass"
}
}
],
"decisions": []
}Wait for completion, then inspect checks[].result.state and checks[].result.verdict. Final verdicts can be pass, partial, fail or inconclusive. Match the reference, tier and environment to your saved record before making your application’s decision.
Poll with backoff, respect rate limits, and stop on completion or expiry. A completed session is not necessarily a pass. Policy decisions are separate; an empty decisions list is not approval.
Your server · Optional
5. Fetch the portrait
Download a JPEG frame for your records or manual review. Read the saved session as in step 4, then find a completed check with an artifact whose kind is portrait and available is true.
{
"id": "ses_example",
"checks": [
{
"id": "chk_example",
"status": "completed",
"portrait_status": "recorded",
"artifacts": [
{
"id": "art_example",
"kind": "portrait",
"available": true
}
]
}
]
}Set CHECK_ID to that check’s id and ARTIFACT_ID to the portrait artifact’s id. Keep using the session ID your server saved for the authenticated user.
curl --fail "$API_ORIGIN/api/v2/sessions/$SESSION_ID/checks/$CHECK_ID/artifacts/$ARTIFACT_ID" \
-H "Authorization: Bearer $API_KEY" \
-o portrait.jpgThe response is image/jpeg. Use an API key for the same account and environment, and keep it on your server. A 404 means the session or artifact is missing, inaccessible or expired.
Extraction may finish after verification. If portrait_status is pending, re-fetch the session with bounded backoff. Stop when the portrait is available, when no_usable_portrait is reported, or on expiry. A completed check does not guarantee a portrait; availability does not change its verdict.
Your server · Optional
6. Receive a completion webhook
For configured destinations, Soliton sends a session.completed JSON POST to your HTTPS endpoint when verification completes. The endpoint must be reachable from the public internet: private and internal addresses are refused. The example below is the notification your server receives, not a response to the result API.
Contact Soliton to enable webhooks. Send us your HTTPS endpoint URL, company and environment (sandbox or production). Continue polling until we confirm your destination is configured.
Content-Type: application/json
Soliton-Signature: t=TIMESTAMP,v1=SIGNATURE{
"id": "evt_example",
"type": "session.completed",
"environment": "sandbox",
"created_at": "2026-10-08T12:00:00Z",
"data": {
"session": {
"id": "ses_example",
"status": "completed",
"check_id": "chk_example",
"result_id": "res_example",
"evidence_verdict": "pass"
},
"session_result_v2": {
"id": "ses_example",
"status": "completed",
"checks": [
{
"id": "chk_example",
"type": "presence",
"status": "completed",
"result": {
"id": "res_example",
"state": "final",
"verdict": "pass"
},
"portrait_status": "pending",
"artifacts": []
}
],
"decisions": []
}
}
}Verify Soliton-Signature using your endpoint’s signing secret and the raw request body. The signature is hex-encoded HMAC-SHA256 over timestamp + "." + rawBody. Validate timestamp freshness and compare signatures in constant time. The signing secret is separate from your API key.
Deduplicate by the event’s id. Match data.session.id and the environment to your stored record; read the result snapshot in data.session_result_v2. Completion is not necessarily a pass.
HTTP/1.1 200 OKAccept and durably record the event before returning 2xx. Failed deliveries get up to five attempts, so your handler must tolerate duplicates. Portrait extraction may still be pending: fetch the latest session as described above. A webhook notifies your server; it does not return the user’s browser to your app.