Biometric Authentication (beta)
This document explains how to integrate the biometric authentication flow for your web or mobile application
This document explains how to integrate and test the biometric authentication feature for your web or mobile application. This guide assumes that you have previously integrated the Verification flow and server-side logic as explained in the Overview & Integration Guide section.
Note: Biometric Authentication is still a beta feature and the results should not be relied upon for sensitive operations in production applications.
Passbase wants to build the identity layer for the internet. Biometric authentication is an important piece of the puzzle. The Biometric authentication feature allows you to verify that the end user is still the person who originally verified their identity with you.
Once your end user's root verification is approved, the user is able to re-authenticate with their unique identifier (their email address and facemap). This is useful if users start a job, approve high transactions or simply login to your app.
The biometric authentication feature must be enabled by the Passbase team. Please reach out to [email protected] to have this feature enabled for your project.
We highly recommend pre-filling the email of the end user to expedite the process, and to ensure the end user does not use a different email address creating a new root identity.
Additionally, we recommend creating logic or logging when an end user is unable to successfully complete the Biometric Authentication. Pass the handler function, onError, through the rendered component to receive an error code of "
BIOMETRIC_AUTHENTICATION_FAILED
" if the end user fails the Biometric Authentication.Property | Description |
apiKey | The API key that you obtained from the developer dashboard |
onFinish: (identityAccessKey: string) => void | identityAccessKey: The UUID of the completed verification |
onError: (errorCode: string, context: { step: StepID }) => void | errorCode: The reason why the flow failed. Can be one of the following:"CANCELLED_BY_USER" | "BIOMETRIC_AUTHENTICATION_FAILED" | "UNSUPPORTED_BROWSER" context: Additional error context information (contains the step where the error occurred)StepID: The step where the error occurred, can be one of the following "START" | "CONSENT" | "EMAIL" | "COUNTRY" | "RESOURCE CHOICE" | "RESOURCE | "SUMMARY" | "FINISHED" |
onStart: () => void | Method that is being called once a user starts the verification flow |
Client-side Web SDK version 3.1.14 or Mobile SDK version
2.1.9
is required.We created a new webhook,
IDENTITY_AUTHENTICATED
, specific to authentication. This webhook will fire when the identity is authenticated successfully.You can test this webhook by adding the event to a new or existing webhook within the Developer Dashboard. Click here to view our webhook documentation including the configuration instructions.
{
"event": "IDENTITY_AUTHENTICATED",
"key": "a11fc1bf-45e0-4317-babf-f40ce1b71f65",
"status": "approved",
"created": 1589550161,
"updated": 1605210019,
"processed": 1589550260,
}
You can find a further description of the response values below:
Key | Data type | Description |
event | string | The type of event that triggered this webhook. |
key | string | The UUID of the Identity which triggered this webhook. This will help you link back to your user as well as query our backend API for the details of the Identity. |
status | string | The authentication was approved. This is triggered by end-user successfully completing reauthentication. |
created | integer | UNIX timestamp, when the Authentication was created |
updated | integer | UNIX timestamp, when the Authentication was updated. |
processed | integer | UNIX timestamp, when the Authentication was processed by Passbase. |
This webhook event will only display in the Developer Dashboard if the Biometric Authentication feature is enabled for your project.
You are now able to see a timeline for each identity under the Verification History tab. You'll be able to see events like when a root identity is created or when authentication is completed or has failed. Additionally, new meta data are now available to give better insights into the verification and authentication event.

An end-user needs to create a root identity first (using a unique email address), that needs to be approved in the project. Once this verification is approved, the end-user is able to authenticate with the same email address if there are no more checks needed (proof of address, insurance card scan, etc.).
- 1.Create a root identity with a unique email address. If you began testing prior to enabling the biometric authentication feature, you will need to create a new root identity with a different email address.
- 2.Once the verification has completed processing, it must be approved in the Developer Dashboard either manually or automatically.
- 3.Complete second verification with the same email address used in root identity.
- 4.Receive
IDENTITY_AUTHENTICATED
webhook event. - 5.
Please update the client-side SDK you are testing to Web SDK version 3.1.14 or Mobile SDK version
2.1.9
and create a new root identity to begin testing the Reauthentication feature.Last modified 7mo ago