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 -> "Pass" | "Fail" (null until the flow completes)
// Other fields are present only for the verifiers you enabled, e.g.
// result.faceId, result.estimatedAge, result.estimatedGender.

if (result.verificationResult === "Pass") {
  // 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()}
/>

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-06-24