HTML + JavaScript

This document explains how to integrate the verification flow into your web application

General

This document explains how to integrate the verification flow directly into your web application through our JavaScript component to verify the identity of your users. This stage might be at the signup page of your application, or at a later point to enrich the profiles of your users. The guide assumes the preliminary steps have already been completed as explained in the initial setup section of the documentation.

We suggest you follow our integration best practices for your wider system in the overview section.

1. Import the Component

Start by adding the minified code to your webpage from the unpkg CDN in the header of your HTML file:

<script
type="text/javascript"
src="https://unpkg.com/@passbase/button@v3/button.js"
></script>

2. Render the Component

Place the new HTML element where you want the component to render inside the body of your HTML file:

<div id="passbase-button"></div>

In order for the button to render correctly, you'll need to pass your apiKey as an argument to the rendering function. Optionally you can also pass in different handler functions like the onFinish, onStart, or onError method to handle different events of the button flow.

Argument

Description

apiKey

The public API Key you obtained from the developer dashboard

onFinish: (identityAccessKey: string) => void

identityAccessKey: UUID of the completed verification. You can use this to query our API.

onError: (errorCode: string) => void

errorCode: Reason why the flow failed

onStart: () => void

Method that is being called once a user starts the verification flow

<script type="text/javascript">
const element = document.getElementById("passbase-button")
const apiKey = "YOUR_API_KEY"
Passbase.renderButton(element, apiKey, {
onFinish: (identityAccessKey) => {},
onError: (errorCode) => {},
onStart: () => {}
})
</script>

Make sure you're using your public API key for this client-side SDK

Add this part below your <div id="passbase-button"></div> element.

The button should now render as shown here:

Speed Up the Verification Flow

During the verification flow, your users will be asked to provide some information which you might already have in your application e.g. the user's email. In this case, you can use the prefillAttributes object to skip the email step.

When the Reauthentication feature is enabled and the email gets prefilled, Passbase will check if the user is already verified on our platform. If yes, the flow will enter the Reauthentication mode. If not, the user enters the normal verification flow and has to provide all required documents selected in your developer dashboard's customization section.

Value

prefillAttributes

email: Your user's email. This will enable skipping the email step.

country: You users' nationality. Will help to pre-select the language and country of the ID document dropdown for your users.

Passbase.renderButton(element, apiKey,
{
prefillAttributes: {
email: "user@email.de",
country: "de"
}
}
)

Reference Your Users

In order for your application to interoperate with Passbase, you need to add a reference to your users once the Verification is completed.

For that, you need to keep track of the identityAccessKey returned by the onFinish callback and associate it in your backend with your users' id. We recommend to either save this key after the onFinish method from your user's completed verification, or listen for the incoming webhooks and make a call to the Passbase API linking back the email address of the user.

<script type="text/javascript">
const element = document.getElementById("passbase-button")
const apiKey = "YOUR_API_KEY"
Passbase.renderButton(element, apiKey, {
onFinish: (identityAccessKey) => {
console.log(identityAccessKey)
// Make a request to your backend/db and save the key
},
onError: (errorCode) => {},
onStart: () => {}
})
</script>

3. UI Customizations

Appearance

Our component currently supports a set of customization options which will influence the appearance of the modal, once opened. The preferred way to customize this is via the developer dashboard's customization section.

Here you can choose amongst a variety of colors, fonts, accepted countries & much more.

Customization Section

The modal also supports a darkMode attribute, which supersedes the effects of any customization selected within the developer dashboard. This is especially useful if your website has a dark UI or you simply want to spare your users' eyes at night. You can activate the darkmode via the theme attribute.

theme

darkMode: A boolean value indicating whether or not to enable the dark theme

enableSystemDarkMode: A boolean value indicating whether the dark mode setting of the users OS should be applied (see https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme)

Passbase.renderButton(element, apiKey,
{
theme: {
darkMode: true,
enableSystemDarkMode: true
}
}
)
Dark Mode

Language

We support a variety of different languages for the verification flow. As of this writing more than 10 including (English, Spanish, German & many more). If one is missing and you want us to add support for it, please reach out to our customer support.

The Verification flow automatically detects the language of the user's browser settings. If we support the language, the verification flow will be set to it. Otherwise the default is English.

Use a Custom Button

In case you want to trigger the Passbase verification flow from a custom button, you can do so by programmatically clicking on the passbase-auth-element. Below is a basic example of how this can be accomplished:

<div class="container">
<!-- 1. This is a custom button component -->
<button class="custom-button" onclick="customClickFunction()">
Custom Button
</button>
<!-- 2. Hide the official Passbase button -->
<div id="passbase-button" hidden></div>
</div>
<script type="text/javascript">
// This is the Verification flow
const element = document.getElementById("passbase-button");
const apiKey = "YOUR_API_KEY";
const onFinish = (identityAccessKey) => {};
Passbase.renderButton(element, apiKey, {
onFinish: onFinish
// No customizations
});
// 4. Custom function
const customClickFunction = () => {
// 5. Programmatically click on the official button element
document.getElementsByClassName("passbase-auth-element")[0].click();
};
</script>

Wrap-up & Example

If you've followed this integration guide, you have successfully integrated Passbase in your Website. You can also check out the code below that shows a working example and compare it with your own solution. To run the code press the Open Sandbox button in the lower right corner.

The demo needs to be in an window in order for the Javascript to work & render the Passbase verification flow. Hence open the Sandbox and then click the Open in New Window button in the top right corner to open the rendered page in a new tab.

You can also find a fully working Web application in our Github repositories.

You have successfully completed the Passbase HTML + JS integration! 🎉