Widget SDK

The Stile widget is a drop-in verification UI for any frontend: two framework-agnostic web components plus a programmatic JavaScript API. Load <stile-frame> from the CDN with a single script tag, or install @stile/widget from npm for the full kit — both speak the same auth modes and emit the same events.

At a glance

Installation

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

npm install @stile/widget

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:

import Stile from "@stile/node";

const stile = new Stile(process.env.STILE_API_KEY!);

export async function POST(req: Request) {
  // Widget sends: { workflowId?, email?, jurisdiction? }
  const { workflowId, email, jurisdiction } = await req.json();

  const session = await stile.verificationSessions.create({
    type: "age",
    workflow_id: workflowId ?? "wf_YOUR_WORKFLOW_ID",
    email,
    jurisdiction,
  });

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

<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

Available via the CDN script or npm. 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"
  workflow-id="wf_YOUR_WORKFLOW_ID"
></stile-frame>

Attributes

Events

<stile-button> — in-page button

Available via npm (@stile/widget). 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"
  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");
});

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_.... Your server should call GET /v1/verification_sessions/:id with your secret key to confirm the result before granting access.

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 more control, use the verify() function from the npm package. It 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 fully custom UIs, use create() to manage the widget lifecycle yourself. 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