HTML + JavaScript

This document explains how to integrate the Authentication flow from your web application

This document explains how to integrate the Authentication directly from your web application through our Javascript component to verify 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 best practice how to integrate Passbase in your wider system in the overview section.

Import the Javascript component

Start by adding the minified code to your webpage from the unpkg CDN:

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

Render the Component

Place the new HTML element where you want the component to render inside your webpage:

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

In order for the button to render correctly, you'll need to pass your previously generated apiKey and a onFinished callback as arguments to the rendering function:

apiKey

The Passbase API Key you obtained from the dashboard

onFinished

error: A string with the reason why the user didn't complete the authentication flow

authKey:The UUID of the completed authentication

additionalAttributes: The Javascript object originally passed to the component

<script type="text/javascript">
const element = document.getElementById("passbase-button")
const apiKey = "YOUR_API_KEY"
const onFinished = (error, authKey, additionalAttributes) => {}
Passbase.renderButton(element, onFinished, apiKey)
</script>

Make sure you're using a publishable API key for this client side integration

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 possess in your application. In this case, you should provide a prefillAttributes object containing the following information:

Value

prefillAttributes

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

country: You users' nationality. Will help to pre-select the right language and ID origin of your user.

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

Customize the Aspect of the iframe

Our component currently supports a set of customization options which will influence the aspect of the modal, once opened. The feature set is bound to grow in the future, subscribe to our newsletter to receive immediate updates upon release.

theme

accentColor: The main color of the main UI components in the flow (button, progress bar)

font: The CSS font-family to customize all text fields present in the UI

fontURL: A URL where to fetch the specified font (if necessary)

buttonColorPreset: Theme color of the "Verify me" button (applicable values: "dark-blue", "mint"). Leave empty for default color.

Passbase.renderButton(element, onFinished, apiKey,
{
theme: {
accentColor: "#ff0000",
font: "Fira",
fontURL: "https://fonts.googleapis.com/css?family=Exo:400,500,600,700,750,800",
buttonColorPreset: "dark-blue"
}
}
)

The configuration above would have the following result:

Enable the Dark Mode (optional)

The modal also supports a darkMode attribute, which supersedes the effects of any other theme attribute

theme

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

systemDarkMode: 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, onFinished, apiKey,
{
theme: {
darkMode: true,
systemDarkMode: true
}
}
)

Reference Your Users

In order for your application to interoperate with Passbase, you need to add a reference to your users once the Authentication is completed. Two options are available:

  1. Keep track of the authKey returned by the onFinished callback and associate it in your backend with your users' id

  2. Pass an additionalAttributes object to the component from your application to retrieve through our API once the Authentication is completed

You are free to choose whichever method suits your application best. Both are described below.

onFinished method

const userId = "SOME_USER_ID"
const onFinished = (error, authKey, additionalAttributes) => {
if(error){
console.error(error)
}else{
fetch(
'/new_authentication', // You have to provide a similar endpoint in your app
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
'authentication_key': authKey,
'user_id': userId
})
}
)
}
}
Passbase.renderButton(element, onFinished, apiKey)

additionalAttributes method

Passbase.renderButton(element, onFinished, apiKey,
{
additionalAttributes: {
customer_user_id: "SOME_USER_ID"
}
}
)

Upon completion of the authentication, it will be retrievable through our API and the dashboard:

Choosing the Integration Type

This parameter specifies that you want to complete a full Authentication, meaning you are seeing this user for the first time in your application and want him to complete the full verification flow. Leave this as integrationType: "signup". This parameter becomes relevant in the Reauthentication section, if you want to trigger the reauthentication flow. e.g. verify that the person is still the same one, who originally signed up.

Passbase.renderButton(element, onFinished, apiKey,
{
integrationType: "signup"
}
)

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. This example below explains it pretty well.

<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 Authentication flow
const element = document.getElementById("passbase-button");
const apiKey = "YOUR_API_KEY";
const onFinished = (error, authKey, additionalAttributes) => {};
Passbase.renderButton(element, onFinished, apiKey, {
integrationType: "signup"
// 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 closely and you've chosen to fully customize your Passbase button, your code should resemble this code snippet:

<html>
<head>
<script src="https://app.passbase.com/button.js"></script>
</head>
<body>
<div id="passbase-button"></div>
<script type="text/javascript">
const element = document.getElementById("passbase-button")
const apiKey = "YOUR_API_KEY"
const onFinished = (error, authKey, additionalAttributes) => {}
Passbase.renderButton(element, onFinished, apiKey,
{
integrationType: "signup",
additionalAttributes: {
customer_user_id: "SOME_USER_ID"
},
prefillAttributes: {
email: "",
country: "en"
},
theme: {
accentColor: "",
font: "Arial"
}
}
)
</script>
</body>
</html>

You can find this code inside a fully working React application in our Github repositories.

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