Signa web SDK

Show a hosted verification session in a dialog on your own page with the Signa web SDK.

The Signa web SDK shows a HOSTED verification session on your website. The person does the steps of the session and stays on your site. The SDK shows the same verification page as the verification_link, in one of two modes:

modeWhat the person sees
embedded (default)A dialog on your page, with the verification page in an iframe. The person does not leave your page.
popupA separate browser window. On a phone, this is a new tab.

Use the web SDK when the person starts the verification on your website. Use the verification_link when you send the verification by email or SMS. Both options use the same session and the same webhook.

The package is @blaaiz/signa-web-sdk. It has no dependencies. It ships ES module and CommonJS builds with TypeScript types.

Before you start

  • Signa must be enabled for your business. Contact your account manager.
  • Your OAuth credentials must carry the compliance-kyc:create and compliance-kyc:read scopes.
  • Your kyc_url webhook must be registered. See Signa webhooks.
  • Read the hosted quickstart. The web SDK uses the same HOSTED session.

Blaaiz decides which verification page a HOSTED session uses. The web SDK can open only a page that Blaaiz hosts. For a session on the page of the Blaaiz verification partner, the access token call returns 422. Send the person the verification_link for that session.

Flow

Step 1: Install the package

npm install @blaaiz/signa-web-sdk

Create the client with the environment of your sessions:

import { createSigna } from '@blaaiz/signa-web-sdk';

const signa = createSigna({ environment: 'production' });
environmentUse it for sessions that you create on
production (default)https://api-prod.blaaiz.com
sandboxhttps://api-dev.blaaiz.com

createSigna uses no browser API, so you can create the client in a module that runs during server rendering. Call startSession in the browser only.

Step 2: Create the session

On your server, create a HOSTED session. Use the same request as the hosted quickstart.

Store the session id against your own record of the person. You need it in step 5.

Step 3: Get an access token

On your server, get an access token for the session. The request takes no body.

curl -X POST https://api-prod.blaaiz.com/api/external/compliance/kyc/sessions/9f2c7b41-6d3e-4c8a-9a20-1e6f0b5d7c33/access-token \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
{
  "message": "Access token issued successfully.",
  "data": {
    "access_token": "L3iqv7TWu9lsfaYAriq_6krLJrYQ0F2uPmhDOhevNWo",
    "expires_at": "2026-10-05T10:44:22.000Z"
  }
}

Send access_token to your page. Do not send the OAuth access token of your server.

The access_token is a bearer credential for the check of one person. Anybody who holds it can do the steps of the session. Do not put it in a URL and do not write it to a log.

Step 4: Show the session

Call signa.startSession():

button.onclick = async () => {
  try {
    const { sessionId } = await signa.startSession({ accessToken });
    // The person finished the steps. Tell your server to wait for the result.
  } catch (error) {
    // error.code is 'closed', 'blocked' or 'in_progress'.
  }
};

By default, the SDK shows the session in a dialog on your page. The dialog has a close button, and the person can also close it with Escape. To use a separate window, pass mode: 'popup':

await signa.startSession({ accessToken, mode: 'popup' });

In popup mode, call startSession() from the click handler of a button. A browser blocks a popup that does not come from a user action. In embedded mode, the browser does not block the dialog.

The verification page asks the person for each step of the session. After the last step, it shows a done screen and the promise resolves. The dialog or the popup closes after 5 seconds, or when the person selects Continue.

The SDK does not go to the redirect_url of the session. If the person opens the verification_link in a new tab, the page goes to the redirect_url as usual.

Use Signa ID works in both modes. The person signs in to Signa ID with an email code each time, in the dialog and in the popup.

Step 5: Get the result

On your server, wait for the merchant.kyc.session.completed webhook. You can also read the session with GET a session.

A resolved promise does not give a result. It tells you only that the person finished the steps. The review can continue after the dialog or the popup closes.

Do not trust a sessionId that your page sends to your server. A person can change it to the id of a different session. On your server, use the session id that you stored in step 2.

Errors in the page

When startSession() rejects, read error.code:

error.codeCauseWhat to do
closedThe person closed the dialog or the popup before the steps were done.Show the button again. The session stays open, and the same access token works until it expires.
blockedpopup mode only. The browser blocked the popup.Call startSession() from a click handler.
in_progressAnother Signa dialog or popup is open on the page.Wait for it to close. Only one can be open at a time.

An accessToken that is not 43 to 64 base64url characters rejects at once. That error has no code. Send the access_token value exactly as Blaaiz returns it.

A second call with the same access token, while its dialog or popup is open, returns the same promise.

Access token rules

  • A token is valid for 30 minutes from when Blaaiz made it. Read expires_at from the response.
  • While the current token has more than 10 minutes left, a new call returns the same token.
  • With 10 minutes or less left, a new call returns a new token. The previous token and the previous verification_link stop working. A dialog or a popup that is open on the previous token also stops working.
  • A new verification link stops the current access token. After you call Issue a verification link, get a new access token before you call startSession().

Get the access token just before you show the button. If the page stays open for a long time, get a new token before the person clicks.

The access token call fails with 422 in these cases:

MessageCause
The web SDK cannot open this session. Send the end customer its verification link instead.The session uses the page of the Blaaiz verification partner.
This session is completed by your server. Upload the documents the set asks for, then submit the session.The session is HEADLESS.
The session is finished; no verification link can be issued.The session is terminal.
The session is not waiting for the end customer; no verification link can be issued.The session is not AWAITING_INPUT.

Page requirements

These requirements also apply to signa.verify() and signa.requestData(). See Wallet status and Request data with Signa ID.

For embedded mode:

  • The verification page uses the camera for the liveness check. If your page sends a Permissions-Policy header, allow the camera for the Signa ID site. For example: Permissions-Policy: camera=(self "https://id.blaaiz.com"). For sandbox, use https://id-dev.blaaiz.com.
  • If your page sends a Content-Security-Policy header with frame-src or child-src, add the Signa ID site.

For popup mode, do not send the Cross-Origin-Opener-Policy: same-origin header on the page. Use same-origin-allow-popups, or send no header. With same-origin, the popup cannot report back to your page.

Next steps

On this page