Integration Guide

This is the production companion to the Quickstart. It covers the decisions that surround the first API call: where policy belongs, how to associate a result with your own transaction, and when verification is strong enough to unlock an action.

All backend examples use the public HTTP API. You can implement the same requests with the standard HTTP client in Node.js, Python, Go, Ruby, PHP, Java, .NET, or any other server platform. No Stile server package is required.

Architecture overview

Every production integration has three trusted boundaries:

1. Your browser renders the hosted <stile-frame> and starts the user experience.
2. Your server authenticates the user, chooses a published workflow, creates a session, and stores the returned session ID against your own transaction.
3. Your webhook handler verifies Stile's signature and atomically applies the result to the matching transaction.

Recommended session-url flow

The public widget POSTs to an endpoint you control. Your endpoint creates the session and returns only the short-lived fields the widget needs.

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

<stile-frame
  mode="modal"
  session-url="/api/start-verification?orderId=order_123"
  workflow-id="wf_YOUR_WORKFLOW_ID"
></stile-frame>

The backend endpoint should perform these operations in order:

1. Require your normal authenticated user session.
2. Apply a per-user and per-IP rate limit.
3. Load the order or action identified by the URL and confirm the user owns it.
4. Map that action to an allow-listed, published workflow_id on the server.
5. POST https://api.stile.id/v1/verification_sessions with your secret Bearer key and a stable Idempotency-Key.
6. Set client_reference_id from the server-loaded transaction, not from an arbitrary browser field.
7. Persist the returned Stile session ID on that transaction.
8. Return { session_id, client_secret, methods, age_tier } to the widget.

The Quickstart session examples show the exact HTTP request in cURL, Node.js, Python, Go, and PHP.

Workflows

Every session requires a published workflow_id. The workflow is the single source of truth for:

• the use case, such as alcohol delivery or account signup;
• target jurisdictions and jurisdiction-specific overrides;
• verification methods and how they compose;
• returning-user preferences;
• session expiry and review behavior.

Do not pass a methods array when you create a workflow-backed session. The API rejects that combination because methods belong to the published workflow.

Create separate workflows for materially different actions. For example, an alcohol checkout and a social account signup usually have different use cases, age tiers, and acceptable methods.

Compliance before session creation

Session creation automatically resolves the workflow's use case against the user's jurisdiction. Use the Compliance API separately when you need product-level decisions before a session exists, such as validating a mixed cart.

curl "https://api.stile.id/v1/compliance/check?use_cases=alcohol_delivery,tobacco_nicotine&jurisdiction=US-CA" \
  --header "Authorization: Bearer $STILE_API_KEY"

The response identifies the most restrictive age tier, allowed methods, and prohibited use cases. Your application decides whether to remove prohibited items, select a different published workflow, or stop checkout.

Returning users

Pass an authenticated user's email or phone when creating a session. If your workflow allows reuse, Stile can resolve an eligible existing credential instead of asking for a full verification again.

{
  "type": "age",
  "workflow_id": "wf_YOUR_WORKFLOW_ID",
  "email": "authenticated-user@example.com",
  "accept_existing": true,
  "client_reference_id": "order_123"
}

A cached VP token can resolve immediately. Otherwise, Stile may require a one-time code to prove control of the email or phone before reusing an organization-scoped credential. The one-time code proves address ownership, not age or identity.

Credential strength and validity still apply. A 21+ credential can satisfy a 16+ workflow, but a 16+ credential cannot satisfy a 21+ workflow. Expired credentials are not reused.

See Returning Users for the full decision tree and Trust Reuse for consent-based reuse across operators.

Delivery and IP mismatch

If your server knows a delivery jurisdiction, include it when creating the session:

{
  "type": "age",
  "workflow_id": "wf_YOUR_WORKFLOW_ID",
  "delivery_jurisdiction": "US-OR",
  "client_reference_id": "order_123"
}

The response can include ip_jurisdiction and jurisdiction_mismatch. A mismatch is a risk signal, not an automatic block. Decide whether your application should warn the user, request a stronger workflow, route the transaction to review, or block it.

Webhook-gated fulfillment

Use the signed webhook as the source of truth. The safe state transition is:

verify signature against raw request body
event = parse JSON

if event.type == "verification_session.verified":
    session = event.data.object

    begin database transaction
      insert event.id into processed_webhook_events with a unique constraint
      if already present: commit and return 200

      update exactly one pending transaction where:
        transaction.stile_session_id == session.id
        transaction.id == session.client_reference_id
        session.status == "verified"

      if exactly one row was not updated: roll back and return 500
    commit

return 200

Use the Webhook Signature Verification guide for complete Node.js, Python, Go, Ruby, and PHP handlers. Return 400 for invalid signatures. Return 5xx for temporary persistence failures so Stile retries. Return 2xx only after the event is safely persisted or queued.

Error handling and retries

Handle these integration errors explicitly:

For 429, honor Retry-After. Retry network failures and temporary 5xx responses with bounded exponential backoff and jitter. Reuse the same Idempotency-Key for each retry of a session-creation operation.

Data retention and privacy

Stile applies workflow and jurisdiction-specific retention controls to collected PII, document evidence, and biometric data. Treat those settings as implementation controls, not a substitute for your own legal and compliance review.

Store only the Stile identifiers and result fields your application needs. Never log secret API keys, webhook secrets, client_secret, document images, or raw identity payloads.

Production checklist

• The workflow is published and belongs to the intended organization.
• The session endpoint requires authentication, ownership checks, and rate limiting.
• Secret keys, workflow selection, identity, and client_reference_id stay server-controlled.
• Session creation uses a stable Idempotency-Key, and the returned session ID is persisted.
• The browser uses the public CDN <stile-frame> with session-url.
• The webhook handler reads the raw body and rejects malformed, stale, or mismatched signatures.
• Event claiming and transaction updates happen atomically and are replay-safe.
• Fulfillment depends only on webhook-backed server state.
• Sandbox tests cover retries, invalid signatures, duplicates, ownership failures, and session mismatches.

Next steps