Search
⌃K

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.

What is Biometric Authentication?

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.

Integration

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.

Webhook Event

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.

Sample Response

{
"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.

Identity History

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.

Testing

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. 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. 2.
    Once the verification has completed processing, it must be approved in the Developer Dashboard either manually or automatically.
  3. 3.
    Complete second verification with the same email address used in root identity.
  4. 4.
    Receive IDENTITY_AUTHENTICATED webhook event.
  5. 5.
    Call Passbase API using server-side library to receive data points from root identity.
Please update the client-side SDK you are testing to Web SDK version 3.1.14 or Mobile SDK version2.1.9 and create a new root identity to begin testing the Reauthentication feature.