FaceKey
Quick Start
Generate your API keys in the VOLTOM dashboard and use clientKey to initialize the SDK. Keep the secret key on your server.
Run the full example in the browser: Open the FaceKey playground.
<button id="facekey-enroll" type="button">Enroll</button>
<script src="https://sdk.voltom.io/v1/facekey.dist.js"></script>
<script type="module">
const facekey = new window.VoltomFaceKey({
clientKey: 'YOUR_CLIENT_KEY',
authorize: async (input) => {
const response = await fetch('/api/facekey/intent', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify(input),
});
const intent = await response.json();
if (!response.ok) throw new Error(intent.code ?? 'INVALID_SERVICE_RESPONSE');
return intent;
},
});
const button = document.querySelector('#facekey-enroll');
button.addEventListener('click', async () => {
button.disabled = true;
try {
const result = await facekey.faceEnroll();
const response = await fetch('/api/facekey/enroll/complete', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ resultId: result.resultId }),
});
if (!response.ok) throw new Error('FACEKEY_COMPLETION_FAILED');
} catch (error) {
console.error(error);
} finally {
button.disabled = false;
}
});
</script>Configure authorize in the constructor. Each operation requests its own intent from your server and returns its resultId. Your server reads the outcome before granting access. Intent tokens expire after five minutes. The SDK opens the camera only when an operation starts.
Configuration Reference
| Option | Type | Default | Description |
|---|---|---|---|
clientKey | string | Required | Public client key from the VOLTOM dashboard. |
prepare | boolean | true | Prepares the SDK at construction. Set false to prepare on demand. Camera access starts when an operation runs. |
apiUrl | string | https://api.voltom.io | API base URL. Accepts absolute HTTP or HTTPS URLs, including a base path. Set from your environment for local development. |
sdkUrl | string | https://sdk.voltom.io | Base URL for models, WASM, locales, and other assets. Uses the same URL rules as apiUrl. All instances in a loaded SDK runtime must use the same sdkUrl; a conflicting URL throws INVALID_OPTIONS. Script and import usage have identical defaults. |
language | Language | Browser language, then en | UI and, in Verify, OCR language. Supports ar, ch, de, en, es, fr, it, ja, pt, ru, zh. Chinese locales zh-TW, zh-HK, and zh-MO select ch. |
theme | 'light' | 'dark' | Host theme, then system | Overrides host .light, .dark, or data-theme selectors and system preference. |
debug | boolean | false | Collects capture diagnostics for state and the debug panel. An operation can override this value. |
authorize | (FaceKeyAuthorizeInput) => Promise<FaceKeyIntent> | Required | Calls your server to create an enroll or unlock intent. |
requireEyeLevelCamera | boolean | true | Requires camera alignment before accepting a face capture. |
capabilities | FaceKeyCapability[] | enroll, unlock | Enables enroll and unlock. An empty list skips capture model preparation. Disabled operations throw SDK_CAPABILITY_NOT_CONFIGURED. |
Omitted options and explicit undefined use defaults. Explicit false is preserved. For local development, pass apiUrl and sdkUrl from your environment.
Operation Options Reference
Operation options apply to one call and override constructor values. Omitted options and undefined retain constructor values.
| Option | Type | Default | Description |
|---|---|---|---|
signal | AbortSignal | None | Cancels the operation when aborted. |
debug | boolean | Constructor value | Overrides debug for this operation. |
Methods Reference
| Method | Result |
|---|---|
preload() | Loads language and model assets before a FaceKey operation. |
prepare() | Calls preload(), prepares the capture interface, and initializes models. |
faceEnroll(options?) | Obtains and consumes an intent. Returns resultId and the enrolled subjectId. |
faceUnlock(options?) | Obtains and consumes an intent. Returns resultId and the unlock result. |
stop() | Stops the active operation, releases the camera, and closes the widget. The client can be reused. |
caniuse() | Returns browser support and unsupported features. |
dispose() | Permanently disposes the client: stops active work, releases the camera, closes the widget, and removes state subscriptions. Do not reuse it; create a new client. Shared model caches remain loaded. |
Flows
Enroll
The SDK calls authorize with action enroll. Your server creates the intent with the secret key. Get subjectId from the authenticated application user. VOLTOM can generate a subjectId when your server does not supply one.
1. Your server: create the intent
app.post('/api/facekey/intent', async (request, response) => {
const upstream = await fetch('https://api.voltom.io/facekey', {
method: 'POST',
headers: { authorization: `Bearer ${process.env.VOLTOM_SECRET_KEY}`, 'content-type': 'application/json' },
body: JSON.stringify({ action: request.body.action, subjectId: request.user.id }),
});
const intent = await upstream.json();
if (!upstream.ok) return response.status(upstream.status).json(intent);
response.json(intent); // resultId, token, subjectId, poses, expiresAt
});2. Browser: run the operation
try {
const result = await facekey.faceEnroll();
const response = await fetch('/api/facekey/enroll/complete', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ resultId: result.resultId }),
});
if (!response.ok) throw new Error('FACEKEY_COMPLETION_FAILED');
} catch (error) {
console.error(error);
}3. Your server: resolve the outcome
app.post('/api/facekey/enroll/complete', async (request, response) => {
const upstream = await fetch(`https://api.voltom.io/facekey/op/${request.body.resultId}`, {
headers: { authorization: `Bearer ${process.env.VOLTOM_SECRET_KEY}` },
cache: 'no-store',
});
const outcome = await upstream.json();
if (!upstream.ok) return response.status(upstream.status).json(outcome);
if (outcome.status !== 'completed') return response.sendStatus(409);
// Validate the result binding to this user, session, and expected operation.
await saveFaceKeyUser({ subjectId: outcome.subjectId });
response.json({ completed: true });
});Unlock
The SDK calls authorize with action unlock. Your server selects the enrolled subject. The SDK captures every requested pose and consumes the token. Any pose that does not match fails the unlock terminally, so retrying requires a new intent and a new token.
1. Your server: create the intent
app.post('/api/facekey/intent', async (request, response) => {
const upstream = await fetch('https://api.voltom.io/facekey', {
method: 'POST',
headers: { authorization: `Bearer ${process.env.VOLTOM_SECRET_KEY}`, 'content-type': 'application/json' },
body: JSON.stringify({ action: request.body.action, subjectId: request.user.id }),
});
const intent = await upstream.json();
if (!upstream.ok) return response.status(upstream.status).json(intent);
response.json(intent);
});2. Browser: run the operation
try {
const result = await facekey.faceUnlock();
if (result.matched) {
const response = await fetch('/api/facekey/unlock/complete', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ resultId: result.resultId }),
});
if (!response.ok) throw new Error('FACEKEY_COMPLETION_FAILED');
}
} catch (error) {
console.error(error);
}3. Your server: resolve the outcome
app.post('/api/facekey/unlock/complete', async (request, response) => {
const upstream = await fetch(`https://api.voltom.io/facekey/op/${request.body.resultId}`, {
headers: { authorization: `Bearer ${process.env.VOLTOM_SECRET_KEY}` },
cache: 'no-store',
});
const outcome = await upstream.json();
if (!upstream.ok) return response.status(upstream.status).json(outcome);
if (outcome.status !== 'completed') return response.sendStatus(403);
// Validate the result binding to this user, session, and expected operation.
await grantAccess({ subjectId: outcome.subjectId });
response.json({ completed: true });
});Forget
Delete an identity from your server with the tenant secret key. This removes the template and invalidates pending intents. A missing identity is accepted.
const response = await fetch(`https://api.voltom.io/facekey/identity/${encodeURIComponent(subjectId)}`, {
method: 'DELETE',
headers: { authorization: `Bearer ${process.env.VOLTOM_SECRET_KEY}` },
});
const result = await response.json();
console.log(result);Results
Technical failures and cancellation reject the operation with a VoltomSdkError. Completed verification and match rejections return a result. Use error.code for decisions. error.message contains stable English text; the SDK UI translates messages separately. HTTP errors include status. Errors for completed results include resultId when available.
import { Errors, isSdkError } from '@voltom.io/sdk/facekey';
try {
const result = await facekey.faceUnlock();
console.log(result);
} catch (error) {
if (!isSdkError(error)) throw error;
if (error.code !== Errors.OPERATION_CANCELLED) {
console.error(error.code, error.message, error.status, error.resultId);
}
}Script integrations use VoltomFaceKey.Errors and VoltomFaceKey.isSdkError. Shared codes include OPERATION_CANCELLED, OPERATION_TIMEOUT, OPERATION_IN_PROGRESS, SDK_DISPOSED, INTENT_TOKEN_INVALID, NETWORK_ERROR, and INVALID_SERVICE_RESPONSE. Cancellation and network errors do not confirm whether a server operation completed. Resolve the result on your server before you retry a protected action.
Enrollment returns resultId and a subjectId. Unlock returns resultId and a match result for the enrolled identity. Identity deletion is a server operation.
type FaceKeyIdentity = { resultId: string; subjectId: string };
type FaceKeyUnlock = {
resultId: string;
subjectId: string;
matched: boolean;
matches: Array<{ pose: FaceKeyPose; matched: boolean; score: number }>;
reason: ErrorCode | null;
};Use matched to present the browser result. Resolve the outcome on your server before granting access. A false value means the identity did not pass the unlock check.
Events
Subscribe to FaceKey events through facekey.events.
| Event | When it fires | Event data |
|---|---|---|
facekey:open | The capture widget opens. | HTMLDialogElement |
facekey:close | The capture widget closes. | None |
facekey.events.addEventListener('facekey:open', (event) => {
const dialog = event.detail;
});
facekey.events.addEventListener('facekey:close', () => {});REST API
Create the intent on your server with the secret key, consume it in the browser with the SDK, then resolve the outcome on your server with the secret key.
| Method | Path | Key | Purpose |
|---|---|---|---|
POST | /facekey | Secret key | Create an enroll or unlock intent. |
GET | /facekey/op/{resultId} | Public or secret key | Read the intent status. |
DELETE | /facekey/identity/{subjectId} | Secret key | Delete an identity and invalidate pending intents. |
Create an intent
// Your server creates the intent with the secret key.
app.post('/api/facekey/intent', async (request, response) => {
const upstream = await fetch('https://api.voltom.io/facekey', {
method: 'POST',
headers: { authorization: `Bearer ${process.env.VOLTOM_SECRET_KEY}`, 'content-type': 'application/json' },
body: JSON.stringify({ action: request.body.action, subjectId: request.user.id }),
});
const intent = await upstream.json();
response.status(upstream.status).json(intent);
});Resolve the outcome
// Your server resolves the outcome with the secret key.
const upstream = await fetch(`https://api.voltom.io/facekey/op/${resultId}`, {
headers: { authorization: `Bearer ${process.env.VOLTOM_SECRET_KEY}` },
cache: 'no-store',
});
const outcome = await upstream.json();
// outcome.status: 'pending' | 'started' | 'failed' | 'completed'
// completed means the enrollment or the unlock succeededLimits and Support
The token for a FaceKey operation expires after five minutes. Each identity includes up to 10 operations per day. For support, write to us through Contact Us.
Pricing Explained
FaceKey costs $0.02 per identity per month. The first 100 identities each month are free. Each identity includes up to 10 operations per day.