Browser SDK — Helix Docs

1. Install the widget

Install it from npm, or load the IIFE build from jsDelivr — it self-attaches to window.Helix:

npm install @helix-id/browser

2. Open the flow

js

import { Helix } from "@helix-id/browser";
// Recommended. Full-page navigation — nothing to block.
document.querySelector("#verify").addEventListener("click", () => {
  Helix.open({
    mode: "redirect",
    startUrl: "/helix/start", // your backend — returns { url }
    onError: (err) => console.error(err),
  });
});

Options

Option	Type	Description
`mode`	`"popup" \| "embed" \| "redirect"`	Defaults to `popup`; pass `redirect` explicitly. Redirect navigates away, so only `onError` can fire, before the navigation.
`container`	`string \| Element`	Embed only, and required there. CSS selector or DOM element the iframe mounts into — give it a height, the iframe is `100%` of it. Embed mode returns a `{ destroy() }` handle so you can tear it down on unmount.
`startUrl`	string	Your endpoint returning `{ url }`. Defaults to `/helix/start`.
`callbackUrl`	string	Popup and embed. Your endpoint verifying the signed callback. Defaults to `/helix/callback`.
`onSuccess`	`(result) => void`	Popup and embed. Called with `{ status, statusCode, logId, enrollmentId? }` on a verified result.
`onError`	`(error) => void`	Called with `{ status: "error", message }` when the SDK itself fails — and with the full callback result (`{ status: "failed", statusCode, … }`, no `message`) on any non-verified verdict. Branch on `statusCode`, not `message`.
`onExit`	`() => void`	Popup only. Called when the user closes the popup early, and once if the popup is blocked — the SDK then falls back to a full-page redirect.

There is no baseUrl option — the widget derives the Helix origin from the url your server returns from createAuthUrl(), so it always targets the environment your server is configured for.

Signature check before redirect

The widget checks that the URL from your startUrl endpoint carries a sig param shaped like an HMAC-SHA256 digest (64 lowercase hex chars). If it is missing or malformed, the widget calls onError with { status: "error", message } instead of opening the popup or mounting the iframe.

The widget holds no secret, so this is a shape check, not cryptographic verification — it catches a misconfigured backend or an obviously rewritten URL, and nothing more. The real guarantees stay server-side: verifyCallback() on the way back, and verifyAuthUrlSignature() if you need to re-check a URL that crossed a service boundary.