Quickstart

This quickstart walks through running a full identity-proofing flow against a local development environment.

1. Sign up and get a test key

1. Start the portal at http://localhost:5173 and create an account.
2. Verify your email (use the local MailDev inbox at http://localhost:1080).
3. Copy the test API key from Portal → API Keys. Test keys look like ak_test_... and work without billing.

2. Create a session from your server

Call POST /v1/sessions. Omit template_id to use your workspace's default verification template (test mode falls back to the platform scaffold when no default is set).

curl -X POST http://localhost:8787/v1/sessions \
  -H "Authorization: Bearer ak_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "metadata": { "customer_id": "cus_123" }
  }'

Pin a specific template by passing template_id (or template_slug).

The response includes a short-lived sdk_token, a session_id, and an iframe_url your frontend will embed.

3. Embed the iframe

Load the returned iframe_url in an <iframe> and pass the session ID and token through URL parameters:

<iframe
  src="https://iframe.kyve.dev?session_id=ses_...&token=..."
  allow="camera; microphone"
  style="width: 100%; min-height: 560px; border: 0"
></iframe>

Listen for postMessage events from the iframe origin — you'll get kyc.ready, kyc.status_changed, and finally kyc.completed or kyc.error.

4. Receive the webhook

When the verification finishes, your webhook endpoint receives a signed verification.completed event. Verify the signature using your endpoint secret, then look up the verification by ID to pull the full result from the API.

See Webhooks for the full event schema and signature format.