Web SDK

The Auvral web SDK mounts the hosted verification flow in an overlay on your page, tells you when it finishes, and removes itself.

It does not handle API keys, create sessions, or talk to the Auvral API. Everything it needs travels in the url your backend already obtained from POST /v1/sessions.

Install

<script src="https://sdk.dev.auvral.com/v1/verification.js"></script>

A dependency-free script that defines one global, window.AuvralVerification.

<script src="https://sdk.auvral.com/v1/verification.js"></script>

Create the session with allowedOrigins

The SDK receives its result from the verification flow, which will only send it to a page whose origin the session explicitly allows. That list comes from your backend, when you create the session:

const res = await fetch(`${process.env.AUVRAL_API_URL}/v1/sessions`, {
  method: "POST",
  headers: {
    "x-api-key": process.env.AUVRAL_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    flowId: process.env.AUVRAL_FLOW_ID,
    referenceId: user.id,
    allowedOrigins: ["https://app.example.com"], // the page that will embed the flow
  }),
});

This environment's API base URL is https://api.dev.auvral.com

Every origin, on purpose

allowedOrigins: ["*"] is supported and means exactly what it says: the flow posts its result to whatever page embeds it. Use it when the embedding origin cannot be known when the session is created, a tenant on its own domain, an agency running the flow for its clients, or localhost on whichever port your dev server picked.

It is all or nothing: ["*"] cannot be combined with a concrete origin, and a list that mixes them answers 400 INVALID_ALLOWED_ORIGINS naming both, because the two ask for opposite things.

The trade is that any page holding the session URL receives that session's events, so the guarantee lasts as long as the URL does. That is short: the code in it is single use, minted by your backend with your secret key, and bound to the first device that opens it. Prefer the explicit list wherever you can write one.

Use it

const auvral = new AuvralVerification();

const frame = auvral.init({
  url: sessionUrl,
  onResult: ({ status, verificationId, sessionId }) => {
    // status is "verified" or "rejected"
  },
  onClose: ({ reason }) => {},
  onError: ({ code, message }) => {},
});

init() returns a handle:

frame.close();  // unmount, idempotent
frame.isOpen;   // boolean

There is no Auvral button component. Connect your own, so it matches your design system:

<button id="verify">Verify identity</button>
<script>
  document.getElementById("verify").onclick = async () => {
    const { url } = await (await fetch("/verification/start", { method: "POST" })).json();
    new AuvralVerification().init({ url, onResult: console.log });
  };
</script>

What the callbacks mean

onResult fires as soon as there is a verdict, and does not close the overlay. Your user may still be reading the final screen. Use the gap: update the page behind them, enable a button, start whatever comes next.

onClose does not mean the verification finished. A close with no preceding onResult means your user left early. Reopening the same url picks up where they stopped, for as long as the session lives. Whether to offer that is your call.

By default the SDK draws its own close button so a user is never trapped behind a full-screen overlay. Pass dismissible: false to remove it.

The rule that matters

onResult arrives in your user's browser, on a page they can open devtools on. Anyone can call your callback with status: "verified" from the console. The SDK rejects messages from anywhere but the verification flow itself, which stops other code on your page forging a result. It can do nothing about the person at the keyboard.

So:

• Use onResult for the interface. A success screen, the next step of your wizard, a spinner while your backend catches up.
• Use the webhook for the decision. Account state, payments, limits, entitlements.

A good pattern is to have onResult poll your own backend, which reports success only once your webhook handler has run.

Before you debug anything

If the overlay does not appear or the camera never turns on, it is almost always a header on your own page. Read Browser requirements first.

Next

• SDK reference: every option, callback and error code.
• SDK versions: every published release, its integrity hash and pinning with SRI.
• Browser requirements: CSP, Permissions-Policy, HTTPS.
• Webhooks: the authoritative result.