Integrating Pinn’s multi-factor authentication service into your web application requires a second step to the typical username/password login flow. Instead of approving access right after verifying a password, your web backend will subsequently interact with Pinn to further verify the user identity.

js sdk chart

For this to work, there will be two communication round-trips between the user's web browser and your web server before an authentication can be considered completely successful.

Thus, integrating Pinn into your web application's authentication code requires:

  • Creating a new web page in your flow, where an iframe dedicated to the Pinn is to be rendered. You will invoke a JavaScript SDK file hosted by Pinn.

  • In your web backend code, creating another HTTP POST handler which verifies an ID Token sent by the Pinn JavaScript SDK. The token is sent through the regular HTTP form mechanism but the form itself is invisible to the user.


Register a Web App with Pinn

To register your web application with Pinn, create a Web App through the Pinn API. This step provides you with a publishable_key that you use below to configure the JavaScript SDK.

Quick Start Integration of the Web SDK

For the web portion of the Pinn SDK integration, simply include the HTML snippet below in a single web page dedicated to Pinn verification. When the page loads, a Pinn authentication Widget will be displayed in an iframe. Since the Widget functions as a "single-page app", no additional pages will need to be created for Pinn use. (You may break up this code snippet into pieces as you deem appropriate for merging into any existing HTML that you may already have.)

    <meta name="viewport" content="width=device-width, initial-scale=1" />
        #pinn_iframe {
            width: 100vw;
            height: 100vh;
            border: none;

<iframe id="pinn_iframe"></iframe>
<form method="post" id="pinn_form"></form>

<script src="https://js.pinn.ai/pinn.js"></script>
        publishable_key: 'THE_PUBLISHABLE_KEY_FOR_YOUR_APP',
        flow: CUSTOM_FLOW,

Single-Page Application

If your web application is a Single-Page App (SPA), then you may want your JavaScript code to be responsible for sending the id_token to your backend. This would prevent the web browser from submitting the form automatically, which would reload the web page and terminate your SPA. In this case, provide a done callback parameter to the Pinn.init() function call. For example, let's assume that your endpoint doesn't accept an HTTP form but is actually a REST endpoint that accepts JSON; you would then initialize Pinn this way:

    publishable_key: 'THE_PUBLISHABLE_KEY_FOR_YOUR_APP',
    flow: CUSTOM_FLOW,

    done function(result) {
        const data = { id_token: result.id_token };
        fetch(window.location.origin + '/pinn_verification', {
            method: 'POST',
            body: JSON.stringify(data),
        .then(/* FILL IN */)
        .catch(/* FILL IN */);

The above example code will work for both successful and failed Pinn verifications, since your backend is responsible for verifying the id_token. Again, this snippet assumes that /pinn_verification is a REST endpoint that accepts JSON; if your target endpoint is an actual form endpoint that accepts an encoding type of "multipart/form-data", then look into FormData.

Configuration of the Web SDK

In the above code snippet, configure the parameters of the Pinn.init() function call as follows:

  1. publishable_key: Replace THE_PUBLISHABLE_KEY_FOR_YOUR_APP with the publishable key that you obtained when creating a Web App through the REST API. It should begin with the letters pk_. This parameter is required.
  2. flow: Replace CUSTOM_FLOW with one or more authentication factors that your organization deems appropriate for a given scenario. The authentication factors should balance security for your organization and convenience for the end user by matching the risk level of the scenario.

Optionally, consider varying the authentication flow in real time based on the user and the context. For example, if a certain type of user is connecting from an international IP address, you may dynamically set a flow that requires more authentication factors.

An example configuration snippet may end up looking like:

    publishable_key: 'pk_5gWZ9wAJbSK9GuK3M9wr234oWnz4gAwGn',
    flow: ['local_biometric', 'either_palm'],


Finish off the web integration by setting up your backend for web.



We are here to help! Contact us with any development related questions at dev@pinn.ai and we'll reach back in a timely manner.