Testing & Sandbox

Stile provides deterministic dashboard fixtures and an organization-level sandbox mode for testing session creation, webhooks, VP tokens, and returning-user flows without verifying a real user. This page explains both tools, local webhook testing, CI suites, and the checklist for moving an integration onto a live organization.

Sandbox mode

Stile runs one API environment, and every organization is live by default. For API-driven tests, ask Stile support to enable sandbox mode on a dedicated testing organization. The base URL and key format do not change. Because each key belongs to one organization, create separate stile_sk_… and stile_pk_… keys for the sandbox and live organizations.

Both follow the same per-key rate limit: 1,000 requests/min for secret keys and 100/min for publishable keys. Use a sandbox org for development, CI pipelines, and pre-production testing. Point your integration at a live org when you're ready to verify real users, then follow the going-live checklist.

Sandbox quota

Sandbox mode is capped at 500 verifications per calendar month per organization. When you hit the cap, session creation returns 402 with code test_quota_exceeded; the quota resets on the 1st of the next month. Sandbox verifications are unbilled, so this cap keeps a runaway CI or load test in check — if you need more volume, run those against a live org.

Deterministic dashboard fixtures

The dashboard's Developers → Test sessions page can create nine deterministic fixture profiles without opening the widget: two verified, four failed, one REQUIRES_INPUT, one cancelled, and one expired. Every fixture creates a session record and emits verification_session.created; the verified, failed, cancelled, and expired profiles also emit their matching terminal session event. This makes the fixtures a fast way to inspect session payloads and exercise those handler branches manually.

The profile labeled Manual review required is a pending-input simulation, not a complete review flow. It leaves the session in REQUIRES_INPUT, creates no review record, and does not emit session_review.flagged. Test review-queue events with a real workflow that routes a session into review.

Use fixtures only in the dedicated sandbox organization. Select a profile, create the session, then open it from the recent list to inspect the session and event records. For automated tests that need to create sessions through your own backend, use skip_verification as described below.

The skip_verification flag

In a sandbox org, pass skip_verification: true when creating a session to skip the entire camera/ID scanning flow. The session transitions straight to verified, fires webhooks, and issues a VP token — all without user interaction.

This is useful for:

• Testing webhook handlers end-to-end
• Validating VP token flows and returning-user logic
• Exercising checkout integrations in CI
• Verifying email binding and OTP behavior

curl -X POST https://api.stile.id/v1/verification_sessions \
  -H "Authorization: Bearer stile_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "age",
    "workflow_id": "wf_YOUR_WORKFLOW_ID",
    "email": "test@example.com",
    "skip_verification": true
  }'

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",
  },
  body: JSON.stringify({
    type: "age",
    workflow_id: "wf_YOUR_WORKFLOW_ID",
    email: "test@example.com",
    skip_verification: true,
  }),
});
const session = await response.json();

The response is identical to a real verified session — same shape, same webhook events, same VP token issuance. Whatever you build against it works unchanged against real verifications.

Local webhook testing

During development your server runs on localhost, which isn't reachable by Stile's webhook infrastructure. Use a tunnel to expose it.

# 1. Start your local server
npm run dev  # listening on port 3000

# 2. In a separate terminal, start ngrok
ngrok http 3000

# 3. Copy the forwarding URL (e.g. https://abc123.ngrok-free.app)
# 4. Register it as a webhook endpoint:
curl -X POST https://api.stile.id/v1/webhook_endpoints \
  -H "Authorization: Bearer stile_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://abc123.ngrok-free.app/api/webhooks",
    "enabled_events": ["verification_session.verified"]
  }'

# 1. Start your local server
npm run dev  # listening on port 3000

# 2. Start the tunnel
cloudflared tunnel --url http://localhost:3000

# 3. Use the generated *.trycloudflare.com URL as your webhook endpoint

Once the endpoint is registered, create a session with skip_verification: true to trigger a real, signed verification_session.verified delivery against your local handler — including the Stile-Signature header, so you can test signature verification exactly as it runs in production.

E2E testing in CI

skip_verification: true is designed for end-to-end suites — it lets you exercise the full integration without camera interactions:

• Session creation and status transitions
• Webhook delivery and signature verification against your real handler
• VP token issuance and returning-user reuse
• Email binding and OTP flows

A typical Playwright/Cypress flow:

1. Create a session with skip_verification: true via your backend.
2. Assert your webhook handler marked the order verified.
3. Assert your UI unlocked.

Keep an eye on the 500/month sandbox quota if your suite runs on every commit.

Sandbox data hygiene

A few best practices to keep your sandbox organization clean:

• Use unique emails per test run — append a timestamp or UUID (e.g. test+1712345678@example.com) to avoid collisions with previous runs.
• Sandbox sessions expire automatically — the default is 24 hours, but a workflow can configure another session timeout. You don't need to delete abandoned sessions manually.
• Isolate testing in a sandbox org — keep your CI and manual testing in a dedicated sandbox organization, separate from the live org that serves real users.

Going live checklist

When your integration works end-to-end in a sandbox org, work through these steps before pointing it at a live organization.

Next steps