Widget SDK

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.

At a glance

Installation

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

Choose an auth mode

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

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:

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

Events

<stile-button> — in-page button

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

Events

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

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.

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.

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.

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);

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

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");
  },
});

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>

Next steps