Missing a country or a custom check? Tell us what you need.Book a 15-min call

Adding Identity Verification to a Web App: A Sandbox-First Guide

How to wire identity or age verification into a web app, from the first sandbox session to webhooks and signed results, and the mistakes that are easy to make on the way.

7 min readNovember 2026

By secuveri teamPublished

A developer integrating identity verification into a web application

The short version

The code for identity verification in a web app is small. Your server creates a session, the person goes through a hosted flow, and your server reads the result. Most integration bugs come from the decisions around that code: which signal you trust, what happens when a request is retried, and what the app does while a case waits for review.

This guide walks through the integration in the order you would build it, using secuveri's API and the open-source example apps. If you want to see the finished thing first, try the bank onboarding demo or the 18+ shop demo. Both run in the sandbox.

How the pieces fit

There are three parts:

  1. Your backend creates a session for one person and one workflow. A workflow is the set of checks you configured, for example identity document, liveness and face match, or a minimum age.
  2. The person completes the flow on a hosted page or in a frame embedded in your app. On a computer, the flow shows a QR code so they can continue on their phone, where the camera and NFC are.
  3. Your backend learns the outcome, through a signed webhook and a signed result it fetches from the API.

The browser is only involved in step 2. That is deliberate, and it shapes the rest of the integration.

Start in the sandbox

Create a sandbox API key in the dashboard under Settings, API keys. Sandbox keys start with sk_test_, production keys with sk_live_. Both belong on your server only.

Next, create and publish a sandbox workflow with the checks you need. If you embed the flow in your page, add your local origin, for example http://localhost:3030, under Settings, Branding, in the list of websites that may embed the flow.

The sandbox runs the real checks, so you can verify with your own document while you build. It also has free scenarios that finish a session immediately with the outcome you choose, approved, declined or sent to review, without a document. Use those to test your code paths. You will want to run the decline and review paths many more times than anyone wants to take a selfie.

Create the session on your server

A session is one API call: POST /v1/sessions with your API key in the x-api-key header, the workflow ID, and your own reference in vendor_data. The response contains a verification ID and the link to the flow. With the Node.js package @secuveri/node, the same call is createSession.

Two details save trouble later:

  • Put your own ID in vendor_data. Use the account ID or order ID the verification belongs to. You will check it again when the result comes back.
  • Send an Idempotency-Key. Derive it from the same ID, for example the order ID. If your request is retried after a timeout, you get the same session back instead of a second one.

Return only the session link or token to the browser. The API key never leaves your server.

Open the flow

You can redirect the person to the link, show it as a QR code, or have secuveri send it by email or SMS. To keep people inside your app, use the browser package @secuveri/web and call Secuveri.start with the session URL. It opens the flow in a modal or inline frame and reports progress through callbacks such as onComplete, onCancel and onError.

Don't trust the browser callback

onComplete means the person reached the end of the flow. It does not mean they passed, and anyone with the developer console can call it. Treat it as a hint to ask your own server for the outcome, never as the outcome itself.

The shop example shows this well. Its checkout only places an order once the server holds an approved result for that order. Calling onComplete by hand changes nothing, because the server still finds no approved result.

Handle the webhook properly

When a verification finishes or is reviewed, secuveri sends a webhook to the endpoint you set under Settings, Webhooks. The webhook receiver example does it in one file. The rules it follows:

  • Verify the signature on the raw body. The secuveri-signature header is an HMAC-SHA256 over the exact bytes received. If your framework parses and re-serialises the JSON first, the signature will not match.
  • Reply fast. Return a 2xx within 10 seconds and do slow work afterwards. Anything else is retried, 7 times over about 21 hours.
  • Deduplicate on the event ID. It stays the same across retries, so store the IDs you have processed.
  • Use the webhook as a trigger. Base the decision on the signed result, not on the webhook body alone.

The webhook endpoint has to be a public https URL. For local development, use a tunnel, or rely on the browser callback plus a server-side result check until you deploy.

Read and check the signed result

Fetch the result with the verification ID (getResult in @secuveri/node). It comes as a signed result: an ES256 JWS that you verify with the public keys at /.well-known/jwks.json. It contains no personal data, so you can keep it as evidence of the decision without storing document images or dates of birth.

Before acting on it, check:

  • It belongs to this case. vendor_data matches your account or order ID, and the workflow ID is the one you expect. Otherwise a valid result from a different, easier workflow could be replayed against your checkout.
  • The status. COMPLETE with an APPROVED verdict lets the person through. REVIEW_REQUIRED means a person on your team still has to decide, so keep the case pending rather than rejecting it. Anything else is not a pass.
  • Specific checks, where they matter. An age-restricted shop, for example, also confirms that the age check in the result meets its own minimum age.

Run the same settlement logic from both the browser path and the webhook path, and make it safe to run twice. Whichever arrives first settles the case, and the second finds nothing left to do.

Test what can go wrong

Before going live, make sure your app behaves sensibly when:

  • The person closes the flow halfway.
  • The result is a decline, or goes to review and is approved a day later.
  • The webhook arrives before the browser callback, or the other way round.
  • The same webhook arrives twice.
  • Your session request times out and is retried.
  • Someone calls your settlement endpoint for an order that has no verification.

Sandbox scenarios cover the outcomes. The rest is ordinary testing of your own code.

Going live

Moving to production is a configuration change: an sk_live_ key, a published production workflow, your production origin in the embed list, and a webhook endpoint with its signing secret. The code stays the same.

The full API reference, including errors and AML screening, is in the dashboard at app.secuveri.com/docs. For an overview of what the API offers, see the developers page.

This article is general information, not legal or compliance advice. Your obligations depend on your sector, licence and markets.

secuveri

Build a verification experience around your business.

Keep exploring

Contact

Talk to us

Tell us what you’re trying to verify. We’ll show you how secuveri can fit your workflow.

We reply within one business day and use your details only for your inquiry. See our privacy policy.