FaceGate
Quick Start
Generate your API keys in the VOLTOM dashboard and use clientKey to initialize the SDK. Call check() before the protected action. Keep the secret key on your server.
Run the full example in the browser: Open the FaceGate playground.
<button id="payout" type="button">Request payout</button>
<script src="https://sdk.voltom.io/v1/facegate.dist.js"></script>
<script type="module">
const facegate = new window.VoltomFaceGate({
clientKey: 'YOUR_CLIENT_KEY',
authorize: async (input) => {
const response = await fetch('/api/facegate/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('#payout');
button.addEventListener('click', async () => {
button.disabled = true;
try {
const result = await facegate.check({ action: 'payout.request' });
if (result.outcome !== 'pass') return;
const response = await fetch('/api/payout', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ resultId: result.resultId }),
});
if (!response.ok) throw new Error('PAYOUT_FAILED');
} catch (error) {
console.error(error);
} finally {
button.disabled = false;
}
});
</script>The server creates the intent with authorize, the SDK consumes it in the browser, and your server resolves the outcome with the resultId. The client result is ignored and the resolved outcome is the only trusted output. The camera opens when your application calls check().
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. |
authorize | (FaceGateAuthorizeInput) => Promise<FaceGateAuthorizedIntent> | Required | Calls your server to create an intent with action, subjectId, and metadata from check(). |
requireEyeLevelCamera | boolean | false | Requires camera alignment before accepting a face capture when enabled. |
Omitted options and explicit undefined use defaults. Explicit false is preserved. For local development, pass apiUrl and sdkUrl from your environment.
Check Options Reference
| Option | Type | Default | Description |
|---|---|---|---|
action | string | Required | Action identifier bound to the token. |
subjectId | string | none | Subject identifier sent to your server when it creates the intent. |
metadata | string | none | Opaque value bound to the intent and returned in the server outcome. |
signal | AbortSignal | none | Cancels a pending check. |
Methods Reference
| Method | Result |
|---|---|
prepare() | Loads assets and prepares the SDK. |
check(options) | Returns Promise<FaceGateCheckResult>. Resolves with pass or fail; rejects technical errors. |
stop() | Stops the camera and clears the active check. |
dispose() | Releases all resources and makes the client unusable. |
caniuse() | Returns browser support and unsupported features. |
Flows
Check an action
Call check() from your click, submit, or navigation handler. A completed check returns pass or fail. Technical failures reject the Promise. Your application manages its controls and runs the protected action after a pass.
try {
const result = await facegate.check({
action: 'payout.request',
subjectId: currentUser.id,
});
if (result.outcome === 'pass') {
await requestPayout({ resultId: result.resultId });
}
} catch (error) {
console.error(error);
}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/facegate';
try {
const result = await facegate.check({ action: 'protected-action' });
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 VoltomFaceGate.Errors and VoltomFaceGate.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.
check() returns { resultId, outcome, reason }, with outcome equal to pass or fail. Authorization, camera, network, timeout, cancellation, and server execution errors reject its Promise. Your server reads the intent outcome before it commits the action.
type IntentOutcome = {
resultId: string;
product: 'facegate';
subjectId: string | null;
action: string;
status: 'pending' | 'consumed' | 'resolved' | 'expired' | 'failed';
outcome: 'pass' | 'fail' | 'error' | null;
reason: ErrorCode | null;
metadata: string | null;
createdAt: string;
expiresAt: string;
consumedAt: string | null;
resolvedAt: string | null;
};A pass is a probabilistic signal. It does not prove legal identity or document authenticity. Error and rejection codes include CAMERA_NOT_FOUND, CAMERA_PERMISSION_DENIED, FACE_NOT_FOUND, OPERATION_TIMEOUT, OPERATION_CANCELLED, NETWORK_ERROR, and INTENT_TOKEN_INVALID.
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 | /facegate | Secret key | Create a FaceGate intent for a protected action. |
GET | /facegate/op/{resultId} | Public or secret key | Read the intent outcome. |
Create an intent
// Your server creates the intent with the secret key.
app.post('/api/facegate/intent', async (request, response) => {
const upstream = await fetch('https://api.voltom.io/facegate', {
method: 'POST',
headers: {
authorization: `Bearer ${process.env.VOLTOM_SECRET_KEY}`,
'content-type': 'application/json',
},
body: JSON.stringify(request.body),
});
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/facegate/op/${resultId}`, {
headers: { authorization: `Bearer ${process.env.VOLTOM_SECRET_KEY}` },
cache: 'no-store',
});
const outcome = await upstream.json();
// outcome.status: 'pending' | 'consumed' | 'resolved' | 'expired' | 'failed'
// outcome.outcome: 'pass' | 'fail' | 'error' | nullLimits and Support
Each FaceGate token is single use and expires shortly after it is issued. A check that reaches the server consumes one billable unit. For support, write to us through Contact Us.
Pricing Explained
FaceGate costs $0.01 per check. The first 1000 checks each month are free. Unused free checks do not roll over. Usage is billed on the first day of each month for the previous month.