Signa web SDK

The Signa web SDK opens a HOSTED verification session in a popup on your website. The person does the steps of the session in the popup and stays on your site. The popup shows the same verification page as the verification_link.

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.

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' });

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.

Step 4: Open the popup

Call signa.startSession() from the click handler of a button. A browser blocks a popup that does not come from a user action.

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'.
  }
};

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

A popup that the SDK opens 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.

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 popup closes.

Errors in the page

When startSession() rejects, read error.code:

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 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 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 open the popup.

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:

Page requirements

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