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:
- Obtain an API token from the Biometry service, and keep it on your backend (see proxy mode below).
- 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-sdkBasic 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 userIdawait 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 IDawait sdk.endSession(sessionId);2. Consents
2.1 Give Authorization Consent
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
userIdfor this user. The parameter is calleduserFullNamefor historical reasons; do not pass the person’s real name.
2.2 Give Storage Consent
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 sessionawait sdk.liveness(videoFile, 'user-123', phrase, { sessionId });
// Later, reuse the same video for face matchingconst 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.