Web SDK

Start the VOVE ID verification journey from a web application.

The Web SDK opens the VOVE ID verification journey and returns the client-side outcome through a callback.

Install

npm install @vove-id/web-sdk

Or:

yarn add @vove-id/web-sdk

Create the session token on your backend. Never put the private x-api-key in browser code.

Start a verification

import { Vove, VoveEnvironment } from '@vove-id/web-sdk';

const vove = new Vove();

vove.start({
  sessionToken: tokenFromYourBackend,
  publicKey: 'public_sandbox_replace_me',
  environment: VoveEnvironment.Sandbox,
  showUI: true,
  onVerificationComplete(status) {
    handleVerificationStatus(status);
  },
});

Use VoveEnvironment.Sandbox with Sandbox credentials and VoveEnvironment.Production with Production credentials.

The callback drives the browser experience. Confirm the current server-side result after a verified webhook before making a final decision.

Configuration

type VoveStatus = 'success' | 'pending' | 'canceled' | 'failed';

interface VoveConfig {
  sessionToken: string;
  publicKey: string;
  environment: VoveEnvironment;
  onVerificationComplete?: (status: VoveStatus) => void;
  showUI?: boolean;
}

Field	Required	Description
sessionToken	Yes	Short-lived token created by your backend.
publicKey	Yes	Public SDK key from the same environment as the token.
environment	Yes	VoveEnvironment.Sandbox or VoveEnvironment.Production.
onVerificationComplete	No	Receives the verification outcome.
showUI	No	Shows or hides the built-in welcome and summary screens. Defaults to true.

The type sketch documents the fields used by start; use the declarations shipped with your installed package as the compile-time authority.

Handle every callback status

function handleVerificationStatus(status: VoveStatus) {
  switch (status) {
    case 'success':
      showAwaitingServerConfirmation();
      break;
    case 'pending':
      showPendingReview();
      break;
    case 'canceled':
      showVerificationCanceled();
      break;
    case 'failed':
      showVerificationFailed();
      break;
  }
}

Hosted-link alternative

You can also open the hosted verification journey directly. Build the URL with URLSearchParams so values such as the redirect URL are encoded correctly.

const params = new URLSearchParams({
  authToken: tokenFromYourBackend,
  publicKey: 'public_sandbox_replace_me',
  environment: 'Sandbox',
  lg: 'en',
  enableVocalGuidance: 'false',
  showUI: 'true',
  redirectURL: 'https://app.example.com/verification-callback',
});

window.location.assign('https://web.voveid.net/?' + params.toString());

The redirect can contain a status query parameter. Treat it as client input and confirm the result on your backend.

Troubleshooting

Symptom	Check
The journey does not start	Confirm the public key, session token, and environment match.
The token is rejected	Request a fresh token from your backend; do not reuse an expired token.
The callback does not run	Check browser errors and confirm the journey reached an outcome.
The hosted redirect is malformed	Construct the URL with URLSearchParams.
Sandbox works but Production does not	Confirm Production access and the approved domain configuration.

See session creation, webhooks, and production readiness.