Web / REST Reference

iLive ships no web SDK binary today. Server and browser integrations call the REST API directly using any HTTP client. The full endpoint catalog — request bodies, response schemas, and a try-it panel — lives at /docs/api, auto-generated from our OpenAPI specification.

This page shows the handful of request patterns most callers need. Use it as a starting template and refer to /docs/api/* for exhaustive schemas.

Base URL

All endpoints are versioned under /v1/ or /v2/ — see /docs/api for the current version of each route.

Authentication

Every request requires an Authorization: Bearer <token> header. Tokens are either long-lived API keys or short-lived JWTs minted for a specific session. See API keys for details.

Authorization: Bearer ilive_live_sk_...
Content-Type: application/json

Recommended patterns

The four patterns below cover most integrations: creating a managed liveness session, verifying its result, comparing two faces, and detecting faces in an uploaded image.

curl -X POST https://api.iliveauth.com/v1/liveness/sessions \
  -H "Authorization: Bearer $ILIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "user_123", "mode": "passive"}'

curl https://api.iliveauth.com/v1/liveness/sessions/$SESSION_ID \
  -H "Authorization: Bearer $ILIVE_API_KEY"

curl -X POST https://api.iliveauth.com/v2/face/compare \
  -H "Authorization: Bearer $ILIVE_API_KEY" \
  -F "reference=@id_photo.jpg" \
  -F "probe=@selfie.jpg" \
  -F "threshold=0.45"

curl -X POST https://api.iliveauth.com/v1/face/detect \
  -H "Authorization: Bearer $ILIVE_API_KEY" \
  -F "image=@photo.jpg"

For every other endpoint — webhooks, batch face search, session replay, admin APIs — see /docs/api.

Handling rate limits

Every API response carries rate-limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset). On 429 Too Many Requests, back off using exponential delay with jitter. Details and per-endpoint limits are documented at /docs/reference/rate-limits.

import random, time, requests
 
def request_with_backoff(method, url, *, max_retries=5, **kwargs):
    for attempt in range(max_retries):
        r = requests.request(method, url, **kwargs)
        if r.status_code != 429:
            return r
        retry_after = float(r.headers.get("Retry-After", 0))
        delay = retry_after or min(2 ** attempt, 30) + random.uniform(0, 1)
        time.sleep(delay)
    return r

Error handling

Errors use a consistent envelope:

{
  "detail": {
    "code": "liveness.face_not_detected",
    "message": "No face detected in the submitted frames.",
    "request_id": "req_01J..."
  }
}

The full code catalog lives at /docs/reference/error-codes. A one-liner for decoding:

def explain_error(response):
    try:
        body = response.json().get("detail", {})
        return f"[{response.status_code}] {body.get('code')}: {body.get('message')}"
    except ValueError:
        return f"[{response.status_code}] {response.text[:200]}"

Always log the request_id — it lets support trace the request end-to-end.

Webhooks

For asynchronous flows (session completed, face-matched, compliance alert), subscribe via webhooks instead of polling. Payloads are signed so you can verify authenticity. See Webhooks for the event catalog and signature verification recipe.

See also