Docs

Widget SDK

The public hosted frame, its session contract, and the private-preview in-page widget APIs.

The public Stile widget is <stile-frame>, a framework-agnostic web component loaded from js.stile.id. The repository also contains an in-page <stile-button> and programmatic JavaScript APIs, but @stile/widget is currently a private preview package rather than a public npm release.

Use the CDN for public integrations today

@stile/widget is marked private in the staging monorepo and is not installable from the public npm registry. External integrations should use the CDN-hosted <stile-frame>. The button, verify(), and create() sections below are retained as private-preview reference for approved consumers and should not be generated into a public integration unless package access has been confirmed.

At a glance

SurfaceDistributionIsolationBest for
<stile-frame>Public CDN (~7 KB launcher)iframe — verification UI runs on Stile's hosted pageExternal integrations, cross-origin isolation, no build step
<stile-button>Private @stile/widget previewIn-page Shadow DOM modal — no iframeApproved preview consumers; instant-open modal via prefetch
verify()Private @stile/widget previewShadow DOM modalApproved preview consumers needing promise-based control
create()Private @stile/widget previewShadow DOM, mounts into your containerApproved preview consumers building a custom UI

Installation

<script src="https://js.stile.id/v1/stile.js"></script>

The CDN script is a ~7 KB (gzipped) launcher that registers the <stile-frame> web component. The verification UI itself runs inside an iframe on Stile's hosted page, so the heavy dependencies (camera, barcode scanning, face detection) never load in your page.

@stile/widget is not published to public npm. If Stile has granted your organization preview access, follow the package-access instructions supplied with that preview; otherwise use the CDN integration above.

Choose an auth mode

Both components support the same three auth modes. Pick one:

Try it — live demo

The frame below is the production widget UI running in demo mode: click through a document-capture flow that always passes. No camera opens, no API is called, and nothing you do is collected — capture and processing steps are simulated on a timer.

Production widget UI in demo mode — no camera, no network, nothing is collected.

The same UI runs inside <stile-frame> / <stile-button> and on the hosted verify page; only the transport differs. To exercise a real end-to-end flow against your own workflow (real sessions, webhooks, and events), use the Workflow Sandbox or a sandbox organization.

The three widget auth modes: backend session via session-url (recommended), pre-minted session via client-secret and session-id, and the legacy publishable-key mode

ModeAttributesWhen to use
Backend session (recommended)session-urlYour backend mints the session with your secret key. The widget POSTs to your endpoint and opens the modal with the result. No publishable key needed in the page.
Pre-minted sessionclient-secret + session-idYou already created the session server-side (e.g. as part of an existing API call) and pass the result down to the page.
Publishable key (legacy)publishable-key + workflow-idThe widget creates the session directly from the browser. Fine for prototypes and sandbox testing; being phased out for production — responses carry a Stile-Deprecation header.

Every mode needs a workflow. Workflows are authored and published in the dashboard and carry the use case, target jurisdictions, verification methods, and preferences — compliance is resolved server-side from the workflow, so you never pass products or age tiers from the client.

The session-url contract

In backend-session mode, the widget sends your endpoint a POST with a JSON body and expects the fields from POST /v1/verification_sessions back:

app/api/start-verification/route.ts
export async function POST(req: Request) {
  // Widget may send: { workflowId?, email?, jurisdiction? }.
  // Treat those values as hints, not authorization or policy.
  const user = await requireAuthenticatedUser(req);
  const actionId = new URL(req.url).searchParams.get("actionId") ?? "";
  const action = await requireOwnedPendingAction(user.id, actionId);

  const response = await fetch("https://api.stile.id/v1/verification_sessions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.STILE_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": `action:${action.id}:age-verification`,
    },
    body: JSON.stringify({
      type: "age",
      workflow_id: process.env.STILE_WORKFLOW_ID!,
      email: user.email,
      client_reference_id: action.id,
    }),
  });
  if (!response.ok) throw new Error(`Stile returned ${response.status}`);
  const session = await response.json();

  await saveStileSessionId(action.id, session.id);

  // Widget expects: session_id + client_secret (methods / age_tier
  // let it render the full step rail instead of a generic fallback)
  return Response.json({
    session_id: session.id,
    client_secret: session.client_secret,
    methods: session.methods,
    age_tier: session.age_tier,
  });
}

This example uses /api/start-verification?actionId=... as the session-url; the server validates that the authenticated user owns the pending action before creating anything. Apply your normal rate limit to the route. Keep workflow and jurisdiction policy on your server, derive identity from the login session, persist the returned Stile session ID, and use a stable idempotency key. The Quickstart shows the complete database and webhook transaction.

<stile-button> POSTs to session-url on mount in the background, so the session is usually ready before the user clicks — the modal opens instantly. If the email or workflow changes after prefetch, the stale session is discarded and re-minted at click time.

<stile-frame> — iframe embed

Publicly available through the CDN script; approved private-preview consumers can also import the component from @stile/widget. The verification UI runs on Stile's hosted page inside an iframe — your page only loads the ~7 KB launcher. Choose this when your JS budget is tight, your infosec team requires cross-origin isolation for third-party code, or you want camera permissions granted once to Stile's origin instead of per merchant.

<script src="https://js.stile.id/v1/stile.js"></script>

<!-- "modal" renders a trigger button that opens the iframe in an overlay -->
<stile-frame
  mode="modal"
  session-url="/api/start-verification?actionId=action_123"
  workflow-id="wf_YOUR_WORKFLOW_ID"
></stile-frame>

Attributes

ParameterTypeDescription
variant"brand" | "light" | "dark"Button style for the modal trigger. brand (default) is the orange fill with white text; light is a bordered white surface with the full-colour lockup; dark is the Stile navy fill. All render as a full-width “Verify with stile” payment-style bar.
session-urlstringBackend-session mode (recommended). URL the frame POSTs to for session creation. See the session-url contract above.
client-secretstringPre-minted-session mode. The session's client secret. Pair with session-id.
session-idstringPre-minted-session mode. The vks_... session ID. Pair with client-secret.
publishable-keystringPublishable-key (legacy) mode. Your stile_pk_ key. Pair with workflow-id.
workflow-idstringID of the published workflow (wf_...). Required in session-url and publishable-key modes.
methodsstringPre-minted mode only: comma-separated methods from the session creation response, so the iframe renders the workflow's full step rail.
age-tierstringPre-minted mode only: the age_tier from the session creation response.
emailstringPre-fills the user's email and powers returning-user lookup.
jurisdictionstringDeclare the jurisdiction (e.g. "US-OR"). Defaults to `US` if omitted.
mode"inline" | "modal"= "inline"inline embeds the iframe in place; modal renders a trigger button that opens the iframe in a full-screen overlay.
labelstring= "Verify"Trigger button text (modal mode).
verified-labelstring= "Verified"Trigger button text after successful verification (modal mode).
heightnumber= 720Fixed inline iframe height in px. The frame keeps this one size for every step; taller screens scroll inside it. Modal mode uses the modal's own fixed size.
min-heightnumber= 400Floor for `height`, kept for existing integrations.
requiredbooleanWhen present inside a <form>, blocks form submission until verified.
form-field-namestring= "stile_session_id"Name of the hidden input injected into the parent form after verification.
confirmation-urlstringYour endpoint to poll for server-side confirmation. When set, stile:server-confirmed fires once your webhook has confirmed the session.

Events

EventDetailDescription
stile:verified{ sessionId, vpToken? }Client-side success signal. Wait for the webhook (or stile:server-confirmed) before granting access.
stile:review{ sessionId, message }The session is held for manual review. Keep fulfillment paused; this is not a failure or a verification.
stile:server-confirmed{ sessionId }Fired after the poll against your confirmation-url reports the webhook-backed state as verified.
stile:error{ message: string }Verification failed.
stile:cancel—User closed the flow.

When a session is held for review, the modal stays open on a neutral "under review" screen and polls for the decision (every 5 seconds for the first 90, then every 30 seconds for up to 15 minutes) — an approval within that window flips the open tab to verified on its own. If the user closes the modal, the trigger renders a neutral "In review" card instead of a retry, and no stile:cancel fires (the flow already settled via stile:review). The decision always also arrives on your backend via the session_review.* and verification_session.* webhooks.

<stile-button> — in-page button

Button styles

Both <stile-button> and <stile-frame>'s modal trigger render as a "Verify with stile" bar that fills its container — cap the width the same way you would a Stripe payment button: with a wrapper, or with the --stile-button-max-width custom property (it inherits through the shadow boundary). Height is fixed; width is the responsive axis. Pick the variant that matches your surface — these are the real components:

brand — orange fill, white action, ink lockup (default)
light — for light merchant surfaces
dark — for dark merchant surfaces
<!-- Cap with a wrapper (the Stripe pattern)… -->
<div style="max-width: 420px">
  <stile-button session-url="/api/start-verification" variant="dark"></stile-button>
</div>

<!-- …or with the custom property -->
<stile-frame
  mode="modal"
  session-url="/api/start-verification"
  variant="light"
  style="--stile-button-max-width: 420px"
></stile-frame>

The default brand variant uses white action text on the orange fill — a deliberate payment-bar aesthetic whose text contrast sits below the WCAG AA threshold (the button's accessible name is carried by aria-label, not the visible text). If your accessibility bar requires AA contrast on the trigger's visible label, use the light or dark variant — both pass.

Available in the private @stile/widget preview. It renders the verification UI directly in your page inside a Shadow DOM modal — no iframe. Same three auth modes and the same event names as <stile-frame>.

<stile-button
  session-url="/api/start-verification?actionId=action_123"
  workflow-id="wf_YOUR_WORKFLOW_ID"
  email-selector="#checkout-email"
></stile-button>

Attributes

ParameterTypeDescription
variant"brand" | "light" | "dark"Button style for the modal trigger. brand (default) is the orange fill with white text; light is a bordered white surface with the full-colour lockup; dark is the Stile navy fill. All render as a full-width “Verify with stile” payment-style bar.
session-urlstringBackend-session mode (recommended). URL the button POSTs to for session creation. Prefetched on mount for an instant click.
client-secretstringPre-minted-session mode. Pair with session-id.
session-idstringPre-minted-session mode. Pair with client-secret.
publishable-keystringPublishable-key (legacy) mode. Pair with workflow-id.
workflow-idstringID of the published workflow (wf_...). Required in session-url and publishable-key modes.
email-selectorstringCSS selector for an email input on the page. The button reads its value automatically.
emailstringPass the email directly instead of using a selector.
jurisdictionstringDeclare the jurisdiction (e.g. "US-OR"). Defaults to `US` if omitted.
success-urlstringURL to redirect to after successful verification. The session ID is appended as a query parameter (e.g. "/done?session_id=vks_...").
cancel-urlstringURL to redirect to if the user cancels verification.
requiredbooleanWhen present inside a <form>, blocks form submission until verification completes. The button shakes if the user tries to submit early.
form-field-namestring= "stile_session_id"Name for the hidden input injected into the parent form after verification.
confirmation-urlstringYour endpoint to poll for server-side confirmation after the client-side success signal.
labelstring= "Verify"Button text.
verified-labelstring= "Verified"Text shown after successful verification.
disabledbooleanDisable the button.

Events

Listen for custom events on the <stile-button> element:

EventDetailDescription
stile:verifiedVerifyResultClient-side success. Wait for webhook-backed confirmation before fulfillment.
stile:review{ sessionId, message }Held for manual review; keep fulfillment paused.
stile:server-confirmed{ sessionId }The merchant confirmation endpoint returned { "status": "verified" }.
stile:error{ message: string }Verification failed, including a confirmation endpoint returning { "status": "failed" }.
stile:cancel—User closed the modal.
const btn = document.querySelector("stile-button");

btn.addEventListener("stile:verified", (e) => {
  console.log("Verified!", e.detail);
  // e.detail.sessionId, etc.
});

btn.addEventListener("stile:error", (e) => {
  console.error("Failed:", e.detail.message);
});

btn.addEventListener("stile:cancel", () => {
  console.log("User cancelled");
});

The confirmation-url contract

Set confirmation-url when you want the component to wait for your server's webhook-backed state. After stile:verified, the widget makes a GET request with the session ID appended as ?sessionId=vks_... and expects JSON:

{ "status": "verified" }

Return { "status": "pending" } while the webhook has not been applied, { "status": "verified" } after your database transaction confirms it, or { "status": "failed" } after a terminal failure. The widget begins polling after 2 seconds, backs off to a 60-second interval, and has no hard timeout by default.

app/api/verification-status/route.ts
export async function GET(request: Request) {
  const user = await requireAuthenticatedUser(request);
  const sessionId = new URL(request.url).searchParams.get("sessionId");

  const order = await db.order.findFirst({
    where: { userId: user.id, stileSessionId: sessionId ?? "" },
    select: { status: true },
  });
  if (!order) return Response.json({ error: "Not found" }, { status: 404 });

  return Response.json({
    status: order.status === "ready_for_fulfillment" ? "verified" : "pending",
  });
}

Authenticate this endpoint and only expose the state of a session owned by the current user. It must read your database state written by the signed webhook—not trust a session ID supplied by the browser as proof.

Zero-JS redirect flow

For the simplest possible integration, use success-url and cancel-url to handle verification results without writing any JavaScript:

<stile-button
  session-url="/api/start-verification"
  workflow-id="wf_YOUR_WORKFLOW_ID"
  success-url="/checkout/complete"
  cancel-url="/cart"
></stile-button>

After verification, the user is redirected to /checkout/complete?session_id=vks_.... Treat that query parameter as untrusted. The destination should look up the matching transaction in your database and wait for the signed webhook to mark it verified. Use GET /v1/verification_sessions/:id only as a server-side reconciliation fallback.

Events (stile:verified, stile:cancel) still fire before the redirect, so you can combine redirect URLs with JavaScript event listeners if needed.

Form integration

When placed inside a <form>, the button automatically injects hidden inputs after verification:

<form action="/api/place-order" method="POST">
  <input name="email" type="email" />
  <input name="address" type="text" />

  <stile-button
    session-url="/api/start-verification"
    workflow-id="wf_YOUR_WORKFLOW_ID"
    email-selector="[name=email]"
    required
  ></stile-button>

  <button type="submit">Place Order</button>
</form>

After verification, the form will include these hidden fields automatically:

<input type="hidden" name="stile_session_id" value="vks_..." />
<input type="hidden" name="stile_verified" value="true" />

The required attribute prevents form submission until the user completes verification. Use form-field-name to customize the hidden input name if your backend expects a different field. <stile-frame> supports the same form gating.

Hidden fields are not proof

stile_session_id and stile_verified are browser-controlled form values. Use them only to find a candidate transaction. Before granting access or fulfilling an order, require the signed webhook-backed state in your database and confirm the stored session belongs to the authenticated user or order.

verify() — JavaScript API

For approved private-preview integrations, verify() opens a modal, handles the entire flow, and returns a promise.

import { verify } from "@stile/widget";

const result = await verify({
  publishableKey: "stile_pk_...",
  workflowId: "wf_YOUR_WORKFLOW_ID",
  email: "user@example.com",
});

console.log(result.sessionId);
ParameterTypeDescription
publishableKeystringYour publishable key. The widget creates the session from the browser (legacy mode).
workflowIdstringID of the published workflow. Required when publishableKey is set — the workflow carries the use case, jurisdictions, and method preferences.
clientSecretstringPre-created session mode: the client_secret from your backend. Pair with sessionId; publishableKey and workflowId are not needed.
sessionIdstringPre-created session mode: the vks_... session ID. Pair with clientSecret.
methodsstring[]Pre-created session mode: pass the methods array from the session creation response so the widget renders the workflow's full step rail.
ageTierstringPre-created session mode: the age_tier from the session creation response (e.g. "min_age_21").
emailstringThe user's email address.
jurisdictionstringSet the jurisdiction. If omitted, the default `US` is used.
returnUrlstringWIDGET-CREATED sessions only. Where the hosted page returns the user after a redirect flow. Defaults to the current page's origin + path — the query string and fragment are deliberately stripped so ambient tokens are never uploaded. Set this if your return route needs specific parameters. It is copied into the session only while the widget creates one with a publishable key: if you pre-create the session yourself (the recommended clientSecret/sessionId mode), this option has NO effect and you must set `return_url` in your server-side session-creation request instead.
onPostReviewOutcome(outcome) => voidCalled if the still-open modal later observes a reviewer's decision. Receives { verified, sessionId?, credentialHash?, message? }. Manual review settles the promise immediately (see below), so this callback is the ONLY programmatic signal for the eventual approval or rejection.

The promise rejects with a VerifyError if the user cancels (error.reason === "cancelled") or if verification fails.

Manual review

If the workflow routes the session to manual review, the promise rejects immediately with error.reason === "review" — the hold is not a failure, so classify it separately from a decline:

import { verify, VerifyError } from "@stile/widget";

try {
  const result = await verify({
    clientSecret,
    sessionId,
    // Fires later, if the modal is still open when a reviewer decides.
    onPostReviewOutcome: (outcome) => {
      // { verified: boolean, sessionId?, credentialHash?, message? }
      updateOrder(outcome.verified ? "verified" : "failed");
    },
  });
  release(result.sessionId);
} catch (error) {
  // `catch` is `unknown` under strict TypeScript — narrow before reading
  // `reason`, and let anything that is not a VerifyError fall through.
  if (!(error instanceof VerifyError)) throw error;
  if (error.reason === "review") {
    // Held for a human. The decision arrives on your webhook endpoint
    // (session_review.approved / .rejected, then the terminal
    // verification_session.* event) — and on onPostReviewOutcome above if
    // the user keeps the modal open.
    markPendingReview();
  } else if (error.reason === "cancelled") {
    markAbandoned();
  } else {
    markFailed();
  }
}

Treat your webhook endpoint as authoritative: the user can close the modal at any point, and onPostReviewOutcome only fires while it is open.

create() — Low-level API

For approved private-preview integrations building fully custom UIs, create() manages the widget lifecycle. Create the session on your backend, then mount the widget with the returned client_secret and session ID:

import { create } from "@stile/widget";

const widget = create({
  clientSecret: session.client_secret, // from your backend
  sessionId: session.id,
  methods: session.methods, // from the same response
  ageTier: session.age_tier,
  onSuccess: (result) => {
    console.log("Verified!", result);
  },
  onError: (error) => {
    console.error("Failed:", error.message);
  },
  onExpired: () => {
    console.log("Session expired");
  },
  onReview: (data) => {
    // Held for manual review — not a failure. `data` may be
    // { sessionId?, message? }; settle your UI on "pending".
    console.log("Held for review:", data?.message);
  },
  // Optional: the workflow's "Accepted document types" allow-list. When
  // non-empty, the document picker only offers these; the server enforces
  // the same list at /document/finish regardless. Hosted-page and
  // <stile-frame> integrations get this automatically from the workflow.
  // The creation response carries the workflow's accepted-document list in
  // metadata (the top-level field exists only on the verify-page context
  // endpoint) — read it from there or the picker will offer types the server
  // rejects at finish.
  allowedDocumentTypes: session.metadata?.allowed_document_types,
});

widget.mount("#verify-container");
// later: widget.destroy()

Framework examples

The web components work natively in any framework:

export function Checkout() {
  return (
    <stile-frame
      mode="modal"
      session-url="/api/start-verification"
      workflow-id="wf_YOUR_WORKFLOW_ID"
    />
  );
}
<template>
  <stile-frame
    mode="modal"
    session-url="/api/start-verification"
    workflow-id="wf_YOUR_WORKFLOW_ID"
  />
</template>
<stile-frame
  mode="modal"
  session-url="/api/start-verification"
  workflow-id="wf_YOUR_WORKFLOW_ID"
/>
<stile-frame
  mode="modal"
  session-url="/api/start-verification"
  workflow-id="wf_YOUR_WORKFLOW_ID"
></stile-frame>

Web components are supported in all modern browsers. The elements auto-register when the script loads — no setup required.

Next steps

Public failure reasons

Document verification declines and failed-session polling expose optional code and category fields alongside the user-facing message. These fields propagate through onError, VerifyError, <stile-frame> and <stile-button> error events, and hosted redirect returns. Existing event names and the reason: "error" discriminator remain compatible; use category to distinguish an intentional decline from a technical failure.

frame.addEventListener("stile:error", ({ detail }) => {
  statusElement.textContent = detail.message;
  if (detail.code === "document_expired") {
    // Ask the applicant to use a current document in a new verification.
  }
});

Public codes include document_expired, document_unreadable, document_type_not_supported, selfie_face_mismatch, and document_unverified. verification_declined is the fallback when a more specific cause is unavailable. verification_processing_error has category technical_error; decline codes have category verification_declined. Fields may be absent on older servers or other error paths. Always retain a message fallback and tolerate new codes.

A decline is not proof of fraud. Public messages omit detector rules, scores, and identity data. A failed session is terminal: a useful reason does not make that same session retryable. Browser events and redirect parameters are informational; confirm outcomes through your backend before granting access.

Terminal failures remain visible inside the verification flow until the applicant selects Close or dismisses the modal. The error event still fires immediately; the launch button does not repeat the failure text. Closing that result screen does not cancel the already-completed session. In hosted redirect flows, the failure return happens after dismissal so the applicant can read the result first. Startup, token, and expiry errors also appear inside the flow, rather than replacing the launch button. Inline integrations show the result within their container. Recoverable capture errors retain their existing retry controls. verify() keeps its promise pending for these errors and calls the optional onError callback; <stile-button> and <stile-frame> emit stile:error with detail.terminal: false for recoverable errors while allowing a later successful retry. Final failure events include detail.terminal: true. Closing a recoverable error emits stile:cancel; closing a terminal result does not. Terminal failures reject the promise immediately and keep the result visible until dismissal.

For custom create() integrations, provide onClose to dismiss your container. An onError payload with terminal: true means the widget is displaying the final result; keep it mounted until dismissal. VerifyError.terminal carries the same flag for verify() consumers. Hosted redirects include error_terminal=true or error_terminal=false; handleVerifyReturn() preserves it on VerifyError.terminal and removes the parameter from the URL. Older redirects without this parameter leave the flag undefined.

Document camera selection

Document capture prefers a standard rear camera when the browser exposes a recognizable camera label. If multiple cameras are available after permission is granted, the camera selector lets the applicant choose another lens. The selected camera is reused for the front and back of the document during the current flow. Selfie capture continues to use the front camera.

Available lenses and their names depend on the device and browser. A website cannot guarantee the phone's native “1x” lens on every iOS or Android device; unnamed cameras retain the browser's rear-camera default until the applicant chooses one. On an iPhone, Safari opens a multi-lens rear camera that changes lens by itself when the ID is close, which makes the picture jump. Where the phone reports that its main lens cannot focus close (recent iPhone Pro models: about 20 cm), the widget reopens with the main lens alone and zooms it 2x, so the ID fills the view from a distance that lens focuses at. Camera selection does not change document verification requirements.

No other camera is zoomed. On iPhone, the widget also asks for a 4K feed instead of 1080p, and the extra resolution keeps the ID's small print legible. A 4K photo is sent as a high-quality JPEG at full resolution, because as a PNG it would exceed the upload size limit.

For the front, a frame wider than 1080 pixels is shown magnified up to 2x about its centre, so the ID fills the guide frame from a distance every phone focuses at. Only the preview is magnified: the whole camera frame is what is captured, uploaded and verified. The back starts unmagnified, so the card fills most of the frame and its barcode has the pixels to be read. On a phone that cannot focus on a card that close (the card stays soft while held still), the back's view is magnified in steps, to 1.5x and then 2x, so the card fills the frame from farther away.

Android phones ask for 4K too when they report at least 4 GB of memory, and 1440p otherwise, so a licence barcode stays readable with the ID further from the camera. These are preferences: a camera that cannot supply them opens at its nearest size. Other devices keep 1080p.

If an ID fills the view but stays out of focus, the widget asks the applicant to move the phone a little farther away.

On the review screen, the photo is cut to the ID with a rim of its surroundings on every side, for display only. The ID is shown as it was photographed and is not straightened, and the cut may reach past the guide frame: the frame says where to hold the ID, not where the review is cut. When no flat card outline is found, the review screen shows the part of the photo the camera screen showed; it never shows the whole camera frame. The original photo is what is verified either way.

A photo is taken only once the camera's picture has been on screen for a moment and the ID has stopped moving through the view.

Before an automatic capture, a frame that looks sharp in the downscaled preview is also checked at the camera's native resolution, so defocus the preview hides, including in low light where sensor grain can pass for detail, does not reach the captured image.

Capture is automatic by default: the applicant lines the document up with the guide frame, and the photo is taken once it has stayed there, sharp, for a moment. Ordinary hand movement does not block a currently sharp image. The widget samples image quality every 150 ms and smooths brief misses; 150 ms is the sampling interval, not a guaranteed capture time. A captured image can be reviewed and retaken.

An Auto / Manual switch sits above the camera. Automatic mode shows no shutter; Manual mode shows one and takes the current frame when it is pressed. After about ten seconds without an automatic capture, the Manual tab is highlighted. File uploads are not offered. Camera startup and scanning have bounded retry states rather than waiting indefinitely.

For an ID card or driver's license, a Vertical ID control on the front turns the guide frame upright for a vertical-format card. The frame turns only when the applicant presses it. The back is always framed across.

For front and other image-quality captures, the widget keeps a small in-memory window of recent usable images and selects the sharpest one, penalizing localized reflections. Old images and images from a changed camera scene are discarded. Glare guidance is advisory; it does not impose a new alignment or stillness rule.

Automatic capture waits until the card spans enough of the view: about half of a magnified view for the front, and 65% of the view for a back whose barcode is read. Blur, insufficient lighting, detected clipping and insufficient document pixels also prevent automatic capture. Browser readiness is acquisition guidance; server checks remain authoritative.

Passports use the photo page. Other supported cards capture front and back. Both sides are taken the same way, as a photo of the whole card lined up with the guide frame. The widget does not read a barcode from the live camera.

For a selected US driver's license, or when the server requests a barcode retake, the PDF417 barcode is read from the back photo after it is taken. Where the browser can take a still photo from the live camera, the back is kept as that still, cut to what the camera screen showed; otherwise it is a video frame. On iPhone and iPad it is always a video frame, because Safari's still is the same size and takes longer. The review screen shows the photo that is kept. The widget reads the barcode from the photo on the device. A read there only spares a wait; when the widget cannot read it, the server checks the photo as soon as it is saved, and the applicant is asked for the back again only if the server cannot read it either. These reads cannot recover obscured barcode data.

When a photo is asked for again, the camera view says so in one line. No banner is shown and no reason is given.

The server stores the original photo and independently decodes it, using its own bounded reading derivatives where needed. For a US driver's license, a photo the server's own reader cannot decode is also put to the document provider's barcode reader. Client-decoded text cannot satisfy the server barcode requirement. The server independently determines document requirements from extracted evidence; picker values cannot bypass its checks.

Built-in guided face capture

The built-in face flow guides the applicant to face the camera, turn in a server-issued random order, and return to center after each turn. Face position and actual head movement drive progress. Processing runs in a worker, with actionable positioning messages and retry handling. Capture completion is followed by server verification; it is not itself a passed result.

The server requires subject continuity and opposite head poses. This built-in gesture check is not a certified presentation-attack detector and still uses AWS face comparison and pose detection. AWS Face Liveness and Azure-selected flows keep their own provider behavior; they are not replaced by this flow.

If the widget cannot confirm a required barcode from a photo, the server checks it as soon as the back is saved. When that also fails, the applicant retakes the back straight away, before any selfie step. This check is capped at about ten seconds and two retakes, and the server still decides from the saved image at the end.

Updated clients request a signed, session-bound head-turn challenge from POST /v1/liveness/:sessionId/challenge. The order remains fixed for that session so network retries and barcode-only retakes preserve valid evidence. The server verifies chronological frames against the issued directions; omitting the ID cannot downgrade an issued challenge. Signing-key verification accepts the same current, previous and legacy overlap keys as session tokens.

Roll out in phases: deploy API support first with BUILTIN_LIVENESS_CHALLENGE_ENFORCE unset, then deploy the updated widget. During this compatibility phase, older clients retain their legacy submission contract; an updated client discovers support through the existing authenticated session-status response. Older APIs omit the capability and use the legacy order without calling a missing challenge route. Authentication, provider and invalid challenge failures on a supporting API never select that fallback. After all supported clients are updated, enable BUILTIN_LIVENESS_CHALLENGE_ENFORCE=1 on the API to bind new built-in sessions at creation. Already-issued challenges remain required even if enforcement is later disabled. Randomized directions do not prove camera origin or prevent all replay.

A face-match-only flow can automatically capture a still when gesture tracking is unavailable; required liveness cannot use this fallback. After bounded local PDF417 attempts, a usable back image can reach the server's authoritative decoder and existing rescan/review policy without a client decode success.

On this page