Managed sessions

A managed session is a server-to-server liveness flow. Your backend creates the session, iLive hosts the capture UI, and the user is redirected back to you when they finish. You never ship an API key to the client, and you never have to build the camera UX.

Managed sessions are the recommended integration for KYC, onboarding, and any regulated workflow.

Lifecycle

Your backend                 iLive                         User's browser

  │   POST /managed-session   │
  │─────────────────────────▶│
  │                           │   session_id + session_url
  │◀─────────────────────────│
  │                                                         │
  │        redirect user to session_url                     │
  │────────────────────────────────────────────────────────▶│
  │                           │   capture + analyse         │
  │                           │◀───────────────────────────▶│
  │                           │                             │
  │                           │   verdict + ICAO photo      │
  │    webhook POST           │                             │
  │◀─────────────────────────│                             │
  │                           │   redirect to redirect_url  │
  │                           │────────────────────────────▶│
  │   GET /session/{id}/result, /photo                      │
  │─────────────────────────▶│                             │
  │◀── result + photo ───────│                             │

Creating a session

Authenticate with your per-tenant API key (iksk_...). Sessions created with a tenant API key are tied to your account, which is what enables signed webhooks:

curl -X POST https://api.iliveauth.com/api/v1/managed-session \
  -H "Authorization: Bearer iksk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "passive",
    "redirect_url": "https://your-app.com/verified",
    "webhook_url":  "https://your-app.com/webhooks/ilive",
    "reference_id": "user-12345"
  }'

The response carries a session_id, a session_url (where you send the user), and a short-lived token you use to fetch the result after the session closes.

A legacy single global key (managed_session_api_key) is still accepted as a Bearer token for back-compat, but sessions created that way are not associated with a tenant account and therefore receive unsigned webhooks. New integrations should always authenticate with a tenant API key.

Both redirect_url and webhook_url must be HTTPS and must not resolve to internal or private IPs. Non-HTTPS URLs are rejected at creation.

While the session is in flight

The user steps through the iLive UI: camera request, face-guide overlay, challenges (if active) or a brief hold (if passive), analysis, and a result screen. The session has a 30-minute TTL from creation; after that, the session URL stops working.

Getting the result

When the session completes, iLive does two things in parallel:

Redirects the user to your redirect_url with the session_id in the query string.
POSTs the verdict to your webhook_url. See Webhooks for payload shape and idempotency guidance.

Your backend should treat the webhook as the authoritative trigger, and then confirm with a server-side pull:

curl "https://api.iliveauth.com/api/v1/session/{session_id}/result?token={token}"

On a pass verdict, download the ICAO photo:

curl -o verified.jpg \
  "https://api.iliveauth.com/api/v1/session/{session_id}/photo?token={token}"

See ICAO photo for format and quality guarantees.

Direct sessions vs managed

If you're building a demo or a standalone consumer app that doesn't have a backend, use a direct session instead — it's created client-side and has no API key. Managed sessions are always the right choice when there is a server that needs to trust the verdict.