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:
mode | What the person sees |
|---|---|
embedded (default) | A dialog on your page, with the verification page in an iframe. The person does not leave your page. |
popup | A 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:createandcompliance-kyc:readscopes. - Your
kyc_urlwebhook must be registered. See Signa webhooks. - Read the hosted quickstart. The web SDK uses the same
HOSTEDsession.
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-sdkCreate the client with the environment of your sessions:
import { createSigna } from '@blaaiz/signa-web-sdk';
const signa = createSigna({ environment: 'production' });environment | Use it for sessions that you create on |
|---|---|
production (default) | https://api-prod.blaaiz.com |
sandbox | https://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.code | Cause | What to do |
|---|---|---|
closed | The 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. |
blocked | popup mode only. The browser blocked the popup. | Call startSession() from a click handler. |
in_progress | Another 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_atfrom 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_linkstop 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:
| Message | Cause |
|---|---|
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-Policyheader, allow the camera for the Signa ID site. For example:Permissions-Policy: camera=(self "https://id.blaaiz.com"). Forsandbox, usehttps://id-dev.blaaiz.com. - If your page sends a
Content-Security-Policyheader withframe-srcorchild-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.