Web SDK

Overview

The VerifEye Web SDK (@realeyes/verifeye-sdk) is a React component library for embedding the VerifEye verification flow directly into your web application. Its single entry point is the VerifyVerifier component, which renders the full client-side experience — camera access, consent, liveness, and image capture — against a verification session you create server-side.

The SDK handles the browser-side capture and the calls to the VerifEye Service. It does not create sessions or expose results on its own:

• Your backend creates a verification session (using your API key) and returns its sessionId and accessToken to the browser.
• The VerifyVerifier component runs the verification using those credentials and invokes onVerificationCompleted when the flow finishes.
• Your backend fetches the outcome from the VerifEye Service API once the flow completes.

Prerequisites

• React 18+ and React DOM 18+
• A VerifEye account and API key from the VerifEye Developer Console.
• A server-side endpoint that creates a verification session and returns its sessionId and accessToken (see Quick Start).
• A secure context (HTTPS) — browsers only grant camera access over HTTPS or localhost.

Installation

npm install @realeyes/verifeye-sdk

Quick Start

1. Create a session on your server

Call the VerifEye Service to create a verification session, authenticating with your API key. The response contains the session ID and a short-lived session token.

// Server-side (Node.js) — never expose your API key to the browser
const res = await fetch(
  "https://verifeye-service-api-eu.realeyes.ai/v1/verification/create-session",
  {
    method: "POST",
    headers: {
      Authorization: `ApiKey ${process.env.VERIFEYE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      verifierConfigs: {
        liveness: { type: "Verification", challengeType: "Balanced" },
        age: { type: "CalculationOnly" },
        gender: { type: "CalculationOnly" },
      },
    }),
  }
);

const { verificationSessionId, sessionToken } = await res.json();
// Return verificationSessionId -> sessionId and sessionToken -> accessToken
// to the browser.

2. Render the component in your React app

Mount VerifyVerifier once the session credentials are available, and react to completion.

import { VerifyVerifier } from "@realeyes/verifeye-sdk";

function Verification({ sessionId, accessToken }: Props) {
  return (
    <VerifyVerifier
      sessionId={sessionId}
      accessToken={accessToken}
      region="eu"
      onVerificationCompleted={(sessionId) => {
        // The flow has finished. Fetch the outcome from your backend, which
        // calls the VerifEye Service "Get Session Result" endpoint.
        console.log("Verification completed for", sessionId);
      }}
    />
  );
}

3. Read the result on your server

When onVerificationCompleted fires, have the browser notify your backend, then fetch the outcome from the VerifEye Service Get Session Result endpoint — again authenticating with your API key, never from the browser.

// Server-side (Node.js) — never expose your API key to the browser
const res = await fetch(
  "https://verifeye-service-api-eu.realeyes.ai/v1/verification/get-session-result" +
    `?verificationSessionId=${sessionId}`,
  {
    headers: {
      Authorization: `ApiKey ${process.env.VERIFEYE_API_KEY}`,
    },
  }
);

const result = await res.json();
// result.verificationResult -> "passed" | "failed" (null until the flow completes)
// Per-verifier results (e.g. result.livenessVerificationResult) can also be
// "not_executed" when that verifier was disabled for the session.
// Other fields are present only for the verifiers you enabled, e.g.
// result.faceId, result.estimatedAge, result.estimatedGender.

if (result.verificationResult === "passed") {
  // Decide what happens next (e.g. allow sign-up).
}

API Reference

VerifyVerifier

const VerifyVerifier: React.FC<VerifyVerifierProps>;

The main React component. Render it to run a single verification session. Each session is single-use — to run another verification, create a new session and remount the component (for example with a new React key).

Props

Supporting types

Region

type Region = "eu" | "us";

The supported VerifEye regions.

ConsentSkipMode

Controls whether the camera-consent screen is shown before capture.

When the consentSkipMode prop is omitted, the consent screen is always shown. See Consent handling for details on when it is safe to skip the built-in consent screen.

VerifyServiceOperation

type VerifyServiceOperation =
  | "init-session"
  | "capture-image"
  | "verify"
  | "unknown";

Identifies which backend operation was in progress when onServiceError was invoked.

HeadlessCallbacks

Lifecycle hooks used in headless mode. All are optional.

Config

Returned by createConfig to control which VerifEye environment the SDK communicates with.

interface Config {
  getCurrentEnvironment(): Environment;
  getApiBaseUrl(): string;
}

Environment

type Environment = "production" | "development" | "local";

Identifies which VerifEye environment a Config targets.

Consent handling

The VerifyVerifier flow accesses the user's camera and processes facial (biometric) data to perform liveness and identity verification. Captured images are used solely to carry out the verification — the SDK does not store them or expose raw biometric data to your application.

Obtaining consent is your responsibility

The hosting application is responsible for obtaining valid, informed user consent for camera access and biometric processing before a verification runs, and for meeting the requirements of the privacy and biometric-data regulations that apply to your users (e.g. GDPR, BIPA, CCPA). See the Realeyes Privacy Policy.

Built-in consent screen

By default, the SDK shows its own consent screen before it requests camera access, so a baseline consent step is always present out of the box. This behaviour is controlled by the consentSkipMode prop:

Usage examples

The following examples mirror how the component is used in the VerifEye Demo application.

Standard verification

The default, interactive flow — the SDK renders its own full-screen UI and drives the user through consent, liveness, and capture.

import { VerifyVerifier } from "@realeyes/verifeye-sdk";

<VerifyVerifier
  sessionId={verifySessionId}
  accessToken={verifyAccessToken}
  region="eu"
  onVerificationCompleted={handleVerificationCompleted}
  showVerificationSessionId={false}
/>;

Headless verification

Set headless to run a verification without the built-in UI — for example, to silently re-verify a user while they keep using your application. Provide headlessCallbacks to hook into the lifecycle, and remount the component with a fresh key and session for each verification cycle.

<VerifyVerifier
  key={session.key}
  headless
  sessionId={session.sessionId}
  accessToken={session.accessToken}
  region="eu"
  onVerificationCompleted={() => onCompleted(session.sessionId)}
  onServiceError={() => onError()}
/>

Reusing a camera stream

By default each headless check opens the camera itself (via getUserMedia) and releases it when the check finishes. When you run checks back-to-back on a short interval, repeatedly acquiring and releasing the camera is wasteful and can make the browser's camera indicator flicker.

Pass a mediaStream to have the SDK capture from a stream you own instead of opening the camera itself. Acquire one long-lived stream, keep it open across cycles, and hand the same stream to each VerifyVerifier mount:

// Acquire once and keep it open for as long as you run checks.
const stream = await navigator.mediaDevices.getUserMedia({ video: true });

<VerifyVerifier
  key={session.key}
  headless
  sessionId={session.sessionId}
  accessToken={session.accessToken}
  region="eu"
  mediaStream={stream}
  onVerificationCompleted={() => onCompleted(session.sessionId)}
  onServiceError={() => onError()}
/>;

// When you are done running checks, stop the tracks yourself.
stream.getTracks().forEach((track) => track.stop());

Keep the following in mind:

• Headless only. Passing mediaStream without headless throws — the interactive flow manages the camera itself.
• You own the stream's lifecycle. The SDK captures from your stream but never stops its tracks. Stop them yourself once you have finished running checks.
• Automatic fallback. If the supplied stream has no live video track (for example the camera was unplugged or its permission was revoked), the SDK falls back to opening the camera itself for that check.

Matching a returning user (Match modes)

Face recognition's match modes (MatchVerification, UniqueMatchVerification, MatchOnlyVerification) perform a 1:1 match against the face stored under your own identifier for the user — for example to re-authenticate a known account instead of sending an SMS/email code. See Verifier choice for how the three modes differ.

The VerifyVerifier usage is unchanged — the match mode is configured entirely server-side when the session is created. Two things matter:

• Set verifierConfigs.faceRecognition.type to the match mode you need.
• Set externalId to your stable identifier for the user (e.g. your user ID). The match modes require it — it selects which enrolled face to match against. Without it, face recognition cannot run and the session fails.

// Server-side (Node.js) — create the session with a match-mode config
const res = await fetch(
  "https://verifeye-service-api-eu.realeyes.ai/v1/verification/create-session",
  {
    method: "POST",
    headers: {
      Authorization: `ApiKey ${process.env.VERIFEYE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      // Your stable identifier for this user — required by the match modes.
      externalId: "user-123",
      verifierConfigs: {
        liveness: { type: "Verification", challengeType: "Balanced" },
        faceRecognition: {
          // MatchVerification: enrolls the face on the user's first visit,
          //   then 1:1-matches on every return visit.
          // UniqueMatchVerification: like MatchVerification, but also fails if
          //   the same face is already enrolled under a different externalId.
          // MatchOnlyVerification: never enrolls — passes only if a face was
          //   already registered under this externalId (fail closed).
          type: "MatchVerification",
          collectionId: "my-collection",
        },
      },
    }),
  }
);

const { verificationSessionId, sessionToken } = await res.json();

The browser then runs VerifyVerifier exactly as in Standard verification. Afterwards, read the outcome server-side:

// Server-side — after onVerificationCompleted fires
const result = await getSessionResult(sessionId); // see "Read the result on your server"

if (result.faceRecognitionResult === "passed") {
  // Same person as the face enrolled under externalId "user-123".
}

Handling service errors

Use onServiceError to react to backend failures and inspect which operation failed.

<VerifyVerifier
  sessionId={sessionId}
  accessToken={accessToken}
  region="eu"
  onVerificationCompleted={handleVerificationCompleted}
  onServiceError={(operation) => {
    // operation: "init-session" | "capture-image" | "verify" | "unknown"
    console.error(`Verification failed during: ${operation}`);
  }}
/>;

Next Steps

• Web SDK Use Cases — common patterns for embedding the VerifEye verification flow into your web application.
• VerifEye Service API — manage verification configurations and retrieve session results server-side.
• Authentication — API key and bearer token authentication for server-side calls.

Last updated: 2026-07-10