---
icon: browser
label: Web SDK
---

# 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`](#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](/cloud-apis-web-sdks/verifeye-service-api/#get-session-result) once the flow completes.

!!!tip
Session creation requires your API key and must happen **server-side only**. Never ship your API key to the browser — the SDK only ever receives a short-lived session `accessToken`.
!!!

---

## Prerequisites

- **React 18+** and **React DOM 18+**
- A **VerifEye account and API key** from the [VerifEye Developer Console](https://verifeye-console.realeyes.ai/).
- A **server-side endpoint** that creates a verification session and returns its `sessionId` and `accessToken` (see [Quick Start](#quick-start)).
- A **secure context (HTTPS)** — browsers only grant camera access over HTTPS or `localhost`.

---

## Installation

```bash
npm install @realeyes/verifeye-sdk
```

---

## Quick Start

### 1. Create a session on your server

Call the VerifEye Service to [create a verification session](/cloud-apis-web-sdks/verifeye-service-api/#create-session), authenticating with your API key. The response contains the session ID and a short-lived session token.

```ts
// 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.

```tsx
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);
      }}
    />
  );
}
```

!!!tip
`onVerificationCompleted` fires when the flow finishes — it does **not** tell you whether verification passed or failed. Retrieve the result server-side via [Get Session Result](/cloud-apis-web-sdks/verifeye-service-api/#get-session-result) using the `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](/cloud-apis-web-sdks/verifeye-service-api/#get-session-result) endpoint — again authenticating with your API key, never from the browser.

```ts
// 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).
}
```

!!!tip
The result returns **all** captured fields regardless of the session's result-parameter configuration, and stays available for **7 days** after the session was created. Fields for verifiers you did not enable are `null`. See [Get Session Result](/cloud-apis-web-sdks/verifeye-service-api/#get-session-result) for the full response schema.
!!!

---

## API Reference

### `VerifyVerifier`

```ts
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

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `sessionId` | `string` | Yes | The verification session ID returned by your server-side `create-session` call. |
| `accessToken` | `string` | Yes | The short-lived session token returned alongside the session ID. |
| `region` | [`Region`](#region) | Yes | The VerifEye region the session belongs to — `"eu"` or `"us"`. Must match the region your backend created the session in. |
| `onVerificationCompleted` | `(sessionId: string) => void` | Yes | Called when the verification flow finishes (regardless of pass/fail). Receives the `sessionId`; use it to fetch the result server-side. |
| `onServiceError` | `(operation: `[`VerifyServiceOperation`](#verifyserviceoperation)`) => void` | No | Called when a backend operation fails. Receives the operation that was in progress when the error occurred. |
| `consentSkipMode` | [`ConsentSkipMode`](#consentskipmode) | No | Controls whether the camera-consent screen is skipped. When omitted, the consent screen is always shown. |
| `headless` | `boolean` | No | When `true`, runs the verification without the built-in full-screen UI. See [Headless verification](#headless-verification). Defaults to `false`. |
| `headlessCallbacks` | [`HeadlessCallbacks`](#headlesscallbacks) | No | Lifecycle hooks for headless mode. Ignored unless `headless` is `true`. |
| `showVerificationSessionId` | `boolean` | No | When `true`, displays the verification session ID in the UI (useful for debugging and support). Defaults to `false`. |
| `createConfig` | `(region: `[`Region`](#region)`) => `[`Config`](#config) | No | Advanced override that supplies a custom [`Config`](#config) controlling which environment and API base URL the SDK targets. When omitted, the SDK targets the production VerifEye Service for the selected `region`. |

---

### Supporting types

#### `Region`

```ts
type Region = "eu" | "us";
```

The supported VerifEye regions.

#### `ConsentSkipMode`

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

| Member | Value | Meaning |
|--------|-------|---------|
| `ConsentSkipMode.SkipIfCameraGranted` | `"1"` | Skip the consent screen only if camera permission has already been granted. |
| `ConsentSkipMode.AlwaysSkip` | `"2"` | Always skip the consent screen. |

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

#### `VerifyServiceOperation`

```ts
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](#headless-verification). All are optional.

| Callback | Type | Description |
|----------|------|-------------|
| `onVerificationStarting` | `() => void` | Called just before the verification begins. |
| `onBeforeCameraAccess` | `() => void` | Called immediately before the SDK requests camera access. |
| `onAfterCameraAccess` | `() => void` | Called once camera access has been resolved. |

#### `Config`

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

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

| Method | Returns | Description |
|--------|---------|-------------|
| `getCurrentEnvironment()` | [`Environment`](#environment) | The environment the SDK should operate against. Client applications must always return `"production"`. |
| `getApiBaseUrl()` | `string` | The base URL of the VerifEye Service the SDK calls. |

!!!warning
You only need a custom `Config` for advanced scenarios. When `createConfig` is omitted, the SDK targets the production VerifEye Service automatically. If you do supply one, `getCurrentEnvironment()` must return `"production"` — the other environments are reserved for internal SDK testing (see [`Environment`](#environment)).
!!!

#### `Environment`

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

Identifies which VerifEye environment a [`Config`](#config) targets.

| Member | Meaning |
|--------|---------|
| `"production"` | The live VerifEye Service. **This is the only value client applications should use** — always return it from [`getCurrentEnvironment()`](#config). |
| `"development"` | An internal pre-production environment used **only for testing the SDK itself**. Not intended for client applications. |
| `"local"` | A developer's local environment used **only when working on the SDK itself**. Not intended for client applications. |


---

## 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](https://realeyes.ai/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`](#consentskipmode) prop:

| `consentSkipMode` | Behaviour |
|-------------------|-----------|
| Omitted (default) | The consent screen is always shown. |
| `SkipIfCameraGranted` | The consent screen is skipped only if camera permission has already been granted. |
| `AlwaysSkip` | The consent screen is never shown. |

!!!warning
Only disable the built-in consent screen (`SkipIfCameraGranted` or `AlwaysSkip`) when your application already obtains equivalent, legally valid consent for camera access and biometric processing before mounting `VerifyVerifier`. If your application does not handle consent itself, leave the built-in consent screen enabled.
!!!

---

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

```tsx
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.

```tsx
<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.

```tsx
<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](/cloud-apis-web-sdks/web-sdk/use-cases/) — common patterns for embedding the VerifEye verification flow into your web application.
- [VerifEye Service API](/cloud-apis-web-sdks/verifeye-service-api/) — manage verification configurations and retrieve session results server-side.
- [Authentication](/cloud-apis-web-sdks/authentication/) — API key and bearer token authentication for server-side calls.

---

*Last updated: 2026-06-24*