Quickstart
From an empty page to a finished measurement, in about ten minutes.
This page walks through the shortest complete integration: an endpoint on your server that issues tokens, the widget on a page, and a result printed in your browser console.
You need an account and an API key. You create the key yourself, in the Test console, on the API Keys page: it is shown only once, right after its creation, so copy it into your server’s secrets at that moment. If you do not have an account yet, contact i-Virtual for a trial.
Everything below runs on Test, which is where a first integration belongs. Production runs the same integration, at different addresses. See Environments.
The API key never goes in a browser
Your API key opens every route of the API, and does not expire unless you gave it a last day. Until you notice a leak and revoke it in the console, it opens your entire account to whoever read it. It belongs on your server and nowhere else. The widget is built so that it never needs to hold it.1. Stand up a token endpoint
At the start of every measurement, the widget asks your application for an access token. Your server answers by calling the API with your key.
Point it at the environment your API key belongs to.
| Environment | API base |
|---|---|
| Production | https://api.saphere.ai |
| Test | https://api.test.saphere.ai |
// server.mjs — Node 20+, Express 4
import express from "express"
const app = express()
app.use(express.static("public")) // serves public/index.html, the page of step 2
const API_BASE = "https://api.test.saphere.ai" // Production: https://api.saphere.ai
const API_KEY = process.env.SAPHERE_API_KEY // never hard-code this
app.post("/api/saphere-token", async (request, response) => {
// Authenticate YOUR user here first. This endpoint mints a credential:
// leaving it open lets anyone spend your measurement quota.
// The widget POSTs { "measurement": "scan" } to this endpoint ("realtime" on
// the real-time screen): mint the token with the permission that matches.
const created = await fetch(`${API_BASE}/access-tokens`, {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${API_KEY}`
},
body: JSON.stringify({
description: "web widget",
// maxSessions: 1 makes the token single-use. Omitting it would
// produce a token replayable until it expires.
permissions: [{ name: "measurement.scan", maxSessions: 1 }],
duration: "15min"
})
})
if (!created.ok)
return response.status(502).json({ error: "could not mint a token" })
// Relay the whole answer: the widget reads `value`, which is the bearer.
// `id` and `expiresAt` open nothing and are safe to keep in your logs.
response.json(await created.json())
})
app.listen(3000)
Check that it works before going further.
curl -sX POST http://localhost:3000/api/saphere-token | jq
{
"id": "8f1c2d34-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"value": "ivat-XCq7…",
"description": "web widget",
"permissions": [{ "name": "measurement.scan", "maxSessions": 1 }],
"expiresAt": "2026-08-24T15:12:44.000Z",
"createdAt": "2026-08-24T14:57:44.000Z"
}
value is shown once
value. A lost token cannot be recovered. It is revoked and replaced.2. Put the widget on a page
The widget is a single JavaScript file served from our CDN. It attaches itself to a div you provide, and fills it.
The CDN address you load it from selects the environment. The widget works out the measurement service from that address on its own, so code served by the Test CDN talks to the Test service and never to Production. Your token endpoint is the one part that does not follow automatically: you point it at the matching API yourself.
| Environment | Module URL |
|---|---|
| Production | https://cdn.saphere.ai/saphere-scan/v2/main.js |
| Test | https://cdn.test.saphere.ai/saphere-scan/v2/main.js |
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Saphere Scan</title>
<style>
html, body { margin: 0; height: 100%; }
/* The widget fills its container, so the container needs a height. */
#scan { height: 100dvh; }
/* On a wide screen, keep it in a phone-shaped column. */
@media (min-width: 40rem) { #scan { aspect-ratio: 9 / 16; margin: 0 auto; } }
</style>
</head>
<body>
<div id="scan"></div>
<script type="module">
import SaphereScan from "https://cdn.test.saphere.ai/saphere-scan/v2/main.js"
const instance = SaphereScan.create("#scan", {
lang: "en",
proxy: {
retrieveAccessToken: {
strategy: "delegate",
url: "/api/saphere-token"
}
},
onEvent: event => {
console.log(event.type, event)
if (event.type === "measure:result")
console.log("variables:", event.result.variables)
if (event.type === "measure:failed")
console.warn("measurement failed:", event.code)
}
})
await instance.bootstrap()
</script>
</body>
</html>
Save it as public/index.html, next to server.mjs: served by the same server as the token endpoint, the page reaches /api/saphere-token with no cross-origin setting, at http://localhost:3000/.
Serve that page over HTTPS, or from localhost. Browsers refuse camera access on any other kind of address, and there is no way around it.
3. Run a measurement
Open the page. You should see the introduction screens, then a consent screen, then four screens of advice on posture, an uncovered face, light and stillness, then the camera.
Sit in even light, facing the camera, and stay reasonably still for thirty seconds. Watch the console: the widget reports every step. The token is asked for when the capture starts, not before, and the images taken while it arrives wait on the device.
widget:ready
detector:loading
screen:enter { path: "/intro", name: "intro" }
detector:loaded
screen:enter { path: "/onboarding/0", name: "onboarding" }
…
consent:accepted
…
screen:enter { path: "/measurement", name: "measurement" }
measure:attempt { attempt: 1 }
camera:requesting
camera:ready { width: 640, height: 480, frameRate: 30 }
placement:started
placement:accepted
measure:start
token:requesting { strategy: "delegate", measurement: "scan" }
token:retrieved
transport:connected
measure:progress { percent: 1 }
…
measure:captures-sent { totalCaptures: 900, totalImages: 1 }
measure:result { result: { … } }
screen:enter { path: "/result", name: "result" }
The trace is abridged: placement:guidance (each time the instruction or the stillness changes) and one measure:progress per percent — the first, percent: 0, as the attempt begins — also appear, on their own clock, independently of the token:* events; camera:released follows measure:captures-sent, and transport:disconnected { reason: "io server disconnect" } comes before measure:result.
4. Read the result
event.result is the finished measurement. The part you want is variables.
{
"id": "5b0e7a9c-2d4f-4a63-9c1e-7f3b8d2a6e10",
"status": "ended",
"returnedVariables": ["hr", "br", "strs"],
"signal": { "qualityScore": { "value": 100, "error": null } },
"variables": {
"hr": { "value": { "mean": 72.4 }, "error": null },
"br": { "value": { "mean": 15.1 }, "error": null },
"strs": { "value": { "level": 2, "scale": { "min": 1, "max": 5 } }, "error": null }
}
}
Every variable is one of two things: a value with error: null, or value: null with an error code saying what went wrong. Always test error before reading value.
Empty returnedVariables?