Skip to content

Web SDK

biometry-web-sdk

The biometry-web-sdk is a software development kit designed to simplify the integration of Biometry’s API services into your web application. Providing tools and utilities enables biometric enrollment (face and voice), liveness checks, and user consent.

Pair it with the React or Angular capture components for the browser side.

Features

  • Consent management: Ask a permission to store their biometric data for authentication using Biometry.
  • Biometric Authentication: Easily authenticate users with biometric data such as voice and face recognition.
  • Face match: Compares extracted image from user’s personal document with the frame from video.
  • Video Processing: Upload and process video files for biometric verification
  • DocAuth: You can check the validity of someones documents through our DocAuth API

Getting Started

Prerequisites

Before you can start using the biometry-web-sdk package, you need to:

  1. Obtain an API token from the Biometry service, and keep it on your backend (see proxy mode below).
  2. Ensure your client side environment is set up (any web framework).

Example

You can find an example in the example/ directory in the Github repository. The example demonstrates how you might integrate the BiometrySDK in a React component with the state.

Installation

To install simply run:

npm install biometry-sdk

Basic Usage (Direct SDK Methods)

After installing, import and instantiate the BiometrySDK. In the browser, use proxy mode (SDK 3.1.0+): point the SDK at your own backend with baseUrl and leave the API key out.

import { BiometrySDK } from "biometry-sdk";
const sdk = new BiometrySDK({
baseUrl: "https://app.example.com/biometry",
// Your own app's credentials, checked by your backend. A function is called
// before every request, so a refreshed token is picked up.
headers: () => ({ Authorization: `Bearer ${getAppSessionToken()}` }),
});

Each call goes to baseUrl plus its own short path: the API v2 path without Biometry’s /api-gateway/v2 prefix. So startSession() calls https://app.example.com/biometry/sessions, liveness() calls .../biometry/liveness, and so on (the defaults are exported as DEFAULT_PROXY_PATHS). Your backend owns these routes and forwards each one to the matching Biometry path, for example POST /liveness to https://api.biometrysolutions.com/api-gateway/v2/liveness. Without an API key the SDK sends no Authorization header of its own.

To use your own route names, override single calls with paths (keys typed as ProxyOperation):

const sdk = new BiometrySDK({
baseUrl: "https://app.example.com",
paths: { endSession: "/biometry-sessions/{session_id}/finish" },
});

Each override must start with /, contain no ? or #, and contain exactly the placeholders of the default path once each ({session_id} for endSession, none for the others). Placeholder values are URI-encoded. An unknown key or an invalid path throws in the constructor. Serve the same new path on your backend and keep forwarding it to the default Biometry path. In the reference proxy, change only the first path of the route’s ROUTES entry and keep its upstream, for example route('POST', '/biometry-sessions/:session_id/finish', { upstream: '/sessions/:session_id/end', ... }). ROUTES writes a path parameter as :session_id; the SDK’s paths writes the same parameter as {session_id}.

Your backend must accept only the SDK’s paths, rebuild each request with user_id set to the signed-in user and only that user’s session_ids, and add Authorization: Bearer <your API key>. See Backend proxy for client SDKs for the full table of default paths and a minimal proxy, including the two jobs your backend does itself: recording consent and owning the liveness challenge. Show the challenge your backend issues for the session (for example as challengeDigits on the face recorder), and pass sessionId to liveness and voiceVerify: the challenge is bound to that session. Pass your backend’s id for the signed-in user as userId, and the challenge you displayed as phrase to liveness and voiceVerify: the proxy overwrites it with its own copy, but those methods still require a non-empty value. faceVerify takes no phrase, so call it as faceVerify(video, userId). Do not set apiKey together with baseUrl, or the SDK sends your Biometry API key to the baseUrl host. If the proxy is on another origin and uses cookies, also pass credentials: "include"; the proxy must then allow credentials in its CORS response. headers, credentials and paths only apply with baseUrl; without it they are ignored (with a console warning). Direct mode is unchanged.

On your own server (Node 18+), pass the key directly:

const sdk = new BiometrySDK("YOUR_API_KEY");

1. Sessions

Session is a way to group transactions together. For example, you can start a session and then use the session ID to link related transactions into a unified group.

const response = await sdk.startSession();
const sessionId = response.body.data.session_id;
const userId = 'user-123';
const phrase = 'one two three four five';
const voiceFile = new File([/* voice audio bytes */], 'voice.wav', { type: 'audio/wav' });
const faceFile = new File([/* face image bytes */], 'face.jpg', { type: 'image/jpeg' });
// Consent is keyed by the same userId (passed as the consent service's userFullName)
await sdk.giveStorageConsent(true, userId, { sessionId });
// Biometric operations are keyed by your opaque userId
await sdk.enrollFace(faceFile, userId);
await sdk.enrollVoice(voiceFile, userId, phrase);
// Go to the Results page in your dashboard and see the transactions grouped by the session ID
await sdk.endSession(sessionId);

2. Consents

You must obtain user authorization consent before performing any biometric operations (Face Recognition, Voice Recognition, etc.):

await sdk.giveAuthorizationConsent(true, 'user-123');
  • The first argument (true) indicates that the user has granted consent.
  • The second argument is your userId for this user. The parameter is called userFullName for historical reasons; do not pass the person’s real name.

You must obtain user consent before storing biometric data (Face Enrollment, Voice Enrollment):

await sdk.giveStorageConsent(true, 'user-123');

3. Face Enrollment

Enroll a user’s face for future recognition or matching:

const faceFile = new File([/* face image bytes */], 'face.jpg', { type: 'image/jpeg' });
await sdk.giveStorageConsent(true, 'user-123');
const faceResponse = await sdk.enrollFace(faceFile, 'user-123');
console.log('Face Enrollment Response:', faceResponse.body.data);

4. Voice Enrollment

Enroll a user’s voice for future authentication checks:

const voiceFile = new File([/* voice audio bytes */], 'voice.wav', { type: 'audio/wav' });
await sdk.giveStorageConsent(true, 'user-123');
const voiceResponse = await sdk.enrollVoice(voiceFile, 'user-123', 'one two three four five');
console.log('Voice Enrollment Response:', voiceResponse.body.data);

5. Verification (Liveness / Face / Voice)

The v1 processVideo call is now three focused methods: liveness, faceVerify, and voiceVerify.

const videoFile = new File([/* file parts */], 'video.mp4', { type: 'video/mp4' });
const phrase = "one two three four five six";
const userId = 'user-123';
await sdk.giveAuthorizationConsent(true, 'user-123');
try {
// Anti-spoof / liveness checks
const response = await sdk.liveness(videoFile, userId, phrase);
// Or verify against an enrolled template:
// const response = await sdk.faceVerify(videoFile, userId); // no phrase needed
console.log('Verification decision:', response.body.decision);
} catch (error) {
console.error('Error verifying:', error);
}

6. Face match

Use matchFaces to compare a reference image (e.g., a document or a captured selfie) against a live capture:

const referenceImage = new File([/* face image bytes */], 'face.jpg', { type: 'image/jpeg' });
const videoFile = new File([/* file parts */], 'video.mp4', { type: 'video/mp4' });
const faceMatchResponse = await sdk.matchFaces(referenceImage, 'user-123', { video: videoFile });

You can also reuse a video captured earlier in the same session by passing useSessionVideo:

const session = await sdk.startSession();
const sessionId = session.body.data.session_id;
// First, run liveness within the session
await sdk.liveness(videoFile, 'user-123', phrase, { sessionId });
// Later, reuse the same video for face matching
const faceMatchResponse = await sdk.matchFaces(referenceImage, 'user-123', {
useSessionVideo: true,
sessionId,
});

7. DocAuth

DocAuth authenticates a user’s document.

const session = await sdk.startSession();
const sessionId = session.body.data.session_id;
const documentFile = new File([/* file parts */], 'document.jpg', { type: 'image/jpeg' });
try {
const response = await sdk.checkDocAuth(documentFile, { sessionId, provider: 'inhouse' });
console.log('DocAuth Response:', response.body.data);
} catch (error) {
console.error('Error checking document:', error);
}

You can find more information in our Github repository

Capture components

The SDK has no UI. For camera and microphone capture that produces upload-ready files, use the component libraries: React or Angular.