VOLTOM
VOLTOM
Por que VOLTOMSoluçõesPreçosCasos de usoDocumentaçãoContacto
Iniciar sessão
Começar
VOLTOMPessoas reais. Internet mais segura.
SobreContactoTermosPrivacidade
← All documentation

FaceGate

VOLTOM FaceGate

  • Quick start
  • Configuration
  • Check options
  • Methods
  • Flows
    • Check an action
  • Results
  • REST API
  • Limits and support
  • Pricing explained
  • Explore FaceKey
  • Explore Verify

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

OptionTypeDefaultDescription
clientKeystringRequiredPublic client key from the VOLTOM dashboard.
preparebooleantruePrepares the SDK at construction. Set false to prepare on demand. Camera access starts when an operation runs.
apiUrlstringhttps://api.voltom.ioAPI base URL. Accepts absolute HTTP or HTTPS URLs, including a base path. Set from your environment for local development.
sdkUrlstringhttps://sdk.voltom.ioBase 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.
languageLanguageBrowser language, then enUI 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 systemOverrides host .light, .dark, or data-theme selectors and system preference.
authorize(FaceGateAuthorizeInput) => Promise<FaceGateAuthorizedIntent>RequiredCalls your server to create an intent with action, subjectId, and metadata from check().
requireEyeLevelCamerabooleanfalseRequires 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

OptionTypeDefaultDescription
actionstringRequiredAction identifier bound to the token.
subjectIdstringnoneSubject identifier sent to your server when it creates the intent.
metadatastringnoneOpaque value bound to the intent and returned in the server outcome.
signalAbortSignalnoneCancels a pending check.

Methods Reference

MethodResult
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.

MethodPathKeyPurpose
POST/facegateSecret keyCreate a FaceGate intent for a protected action.
GET/facegate/op/{resultId}Public or secret keyRead 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' | null

Limits 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.