Authorization: Bearer sk_test_…

onboarding:create  POST /v1/onboarding/sessions
onboarding:read    GET  /v1/onboarding/sessions/{id}

# Create-only key — e.g. a signup service that starts onboarding
scopes: onboarding:create

# Read-only key — e.g. a reconciliation job or webhook consumer that confirms results
scopes: onboarding:read

# Standard integration key — one backend that does both
scopes: onboarding:create, onboarding:read

curl -X POST https://<host>/api/public/v1/onboarding/sessions \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: signup-8f3a21c9" \
  -H "Content-Type: application/json" \
  -d '{
    "client_reference": "user_1042",
    "country": "GH",
    "document_type": "ghana_card",
    "return_url": "https://app.example.com/kyc/done"
  }'

{
  "id": "onb_X7k2pQ9mR4tVwY1z",
  "object": "onboarding_session",
  "livemode": false,
  "status": "created",
  "client_reference": "user_1042",
  "expires_at": "2026-10-07T17:00:00.000Z",
  "verification_policy": {
    "id": "gh.ghana_card.sandbox",
    "version": "2026.10.0",
    "country": "GH",
    "document_type": "ghana_card",
    "authoritative_required": false,
    "document_capture": true,
    "sandbox_simulation": true,
    "lawful_exception": false
  },
  "hosted_url": "https://<host>/onboard?s=onb_X7k2pQ9mR4tVwY1z&t=…"
}

curl https://<host>/api/public/v1/onboarding/sessions/onb_X7k2pQ9mR4tVwY1z \
  -H "Authorization: Bearer sk_test_…"

{
  "id": "onb_X7k2pQ9mR4tVwY1z",
  "object": "onboarding_session",
  "livemode": false,
  "status": "approved",
  "current_step": "complete",
  "client_reference": "user_1042",
  "created_at": "2026-10-06T16:40:00.000Z",
  "completed_at": "2026-10-06T16:47:12.000Z",
  "expires_at": "2026-10-07T17:00:00.000Z",
  "verification_policy": { "id": "gh.ghana_card.sandbox", "version": "2026.10.0", … },
  "result": {
    "onboarding_id": "onb_X7k2pQ9mR4tVwY1z",
    "status": "approved",
    "legal_full_name": "…",
    "date_of_birth": "…",
    "identity_reference": "GHA-********-*",
    "checks": {
      "document": "passed",
      "liveness": "passed",
      "face_match": "passed",
      "duplicate_face": "no_match",
      "authoritative_identity": "not_performed"
    },
    "risk_level": "not_assessed",
    "ghana_card_verified": false,
    …
  }
}

identityos-signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>

const [t, v1] = header.split(",").map((p) => p.split("=")[1]);
const expected = createHmac("sha256", webhookSecret)
  .update(`${t}.${rawBody}`)   // exact request body, unparsed
  .digest("hex");

if (Math.abs(Date.now() / 1000 - Number(t)) > 300 ||
    !timingSafeEqual(Buffer.from(v1), Buffer.from(expected))) {
  return res.status(401).end();
}

{
  "id": "evt_…",
  "type": "onboarding.completed",
  "created_at": "…",
  "data": { "onboarding_id": "onb_…", "client_reference": "user_1042", "state": "approved" }
}

{
  "error": {
    "code": "unsupported_document",
    "message": "Unsupported country/document combination."
  }
}

import { IdentityOS, constructEvent, SIGNATURE_HEADER } from "@identityos/node";

const identity = new IdentityOS({
  apiKey: process.env.IDENTITYOS_SECRET_KEY!,   // sk_test_… or sk_live_…
  baseUrl: process.env.IDENTITYOS_BASE_URL!,
});

// Idempotency-Key is generated automatically, so retries never duplicate sessions.
const session = await identity.onboardingSessions.create({
  client_reference: "user_1042", country: "GH", document_type: "ghana_card",
});
// Send session.hosted_url to your frontend. Store session.id.

const latest = await identity.onboardingSessions.retrieve(session.id);
latest.result?.checks.authoritative_identity; // "not_performed" until an authority is connected

// Webhooks: pass the RAW body, not parsed JSON.
const event = await constructEvent({
  payload: rawBody, signature: req.headers[SIGNATURE_HEADER], secret: process.env.IDENTITYOS_WEBHOOK_SECRET!,
});

import { launchOnboarding } from "@identityos/web";

button.onclick = () => launchOnboarding({
  // Your backend creates the session and returns only hosted_url.
  hostedUrl: fetch("/api/identity/start", { method: "POST" }).then((r) => r.json()).then((j) => j.hosted_url),
  mode: "popup",                          // or "new_tab" / "redirect"
  allowedOrigins: ["https://identity.example.com"],
  checkStatus: (id) => fetch(`/api/identity/status/${id}`).then((r) => r.json()).then((j) => j.status),
  onAdvisoryComplete: (msg) => { /* verified signal, not authoritative */ },
  onComplete: (status, { source }) => { /* source "backend" = confirmed by your server */ },
  onClose: () => { /* closed before finishing */ },
});

import { IdentityOSOnboarding } from "@identityos/react";

<IdentityOSOnboarding
  getHostedUrl={() => startOnServer()}
  checkStatus={(id) => statusFromServer(id)}
  allowedOrigins={["https://identity.example.com"]}
  onComplete={(status, { source }) => source === "backend" && setStatus(status)}
>
  Verify your identity
</IdentityOSOnboarding>

App                         Your backend                 IdentityOS
 │ tap "Verify" ───────────▶ create()  (sk_ key) ───────▶ POST /v1/onboarding/sessions
 │ ◀──────── hosted_url ──── ◀──────────────────────────
 │ launch(hosted_url) ─────────────────────────────────▶ hosted flow (browser)
 │ poll status / on resume ▶ retrieve() (sk_ key) ─────▶ GET /v1/onboarding/sessions/{id}
 │ ◀──────── status ─────── ◀──── + signed webhooks ────

Backend ── POST /v1/onboarding/sessions { return_url } ──▶ IdentityOS
App     ── open hosted_url (popup / browser) ─────────────▶ hosted flow
Hosted  ── postMessage(msg, exact return origin) ─▶ opener   (web popup only, advisory)
Hosted  ── redirect return_url?identityos_session_id=…&identityos_status=…  (advisory)
App     ── "check my session" ──▶ Backend ── GET /v1/onboarding/sessions/{id} (authoritative)
                                   Backend ◀── signed webhook (authoritative)

{
  "type": "identityos.onboarding.complete",
  "version": 1,
  "session_id": "onb_…",
  "status": "approved" | "rejected" | "manual_review" | "expired",
  "livemode": false,
  "completed_at": "2026-10-06T12:00:00.000Z"
}

// React Native
listenForReturnLink({ expectedSessionId: session.sessionId,
  allowedReturnOrigins: ["https://app.example.com"],
  onReturn: () => watch.checkNow() });

// Flutter (feed URIs from app_links or your own channel)
final r = parseReturnLink(uri.toString(), expectedSessionId: id, allowedReturnOrigins: ['https://app.example.com']);

// iOS (.onOpenURL / NSUserActivity.webpageURL)
let r = try ReturnLink(url: url, expectedSessionID: id, allowedReturnOrigins: ["https://app.example.com"])

// Android (App Link activity)
val r = ReturnLink.parse(intent.data.toString(), id, listOf("https://app.example.com"))

import { launchHostedSession, watchSessionStatus } from "@identityos/react-native";

const { session } = await launchHostedSession({ hostedUrl, allowedOrigins: ["https://identity.example.com"] });
const watch = watchSessionStatus({
  sessionId: session.sessionId,
  checkStatus: (id) => myBackend.status(id),     // your server calls retrieve()
  onComplete: (status) => setStatus(status),
});
// re-checks when the app returns to the foreground; call watch.dispose() on unmount

final launch = await IdentityOS.launch(hostedUrl, allowedOrigins: ['https://identity.example.com']);
final poller = SessionStatusPoller(
  sessionId: launch.session.sessionId,
  checkStatus: (id) async => parseStatusOrThrow(await myBackend.status(id)),
  onComplete: (s) => print(s.wire),
)..start();
ResumePollingObserver(poller); // re-check on resume

let session = try HostedSession(hostedURL: hostedURL, allowedOrigins: ["https://identity.example.com"])
launcher.present(session, from: self)            // SFSafariViewController
let poller = try SessionStatusPoller(sessionID: session.sessionID,
  provider: ClosureStatusProvider { id in try await myBackend.status(id) })
for try await status in await poller.statuses() where status.isTerminal { /* done */ }

val launch = IdentityOS.launch(this, hostedUrl, allowedOrigins = listOf("https://identity.example.com"))
poller = SessionStatusPoller(launch.session.sessionId,
  { id -> SessionStatus.fromWire(myBackend.status(id)) }, listener).also { it.start() }

override fun onResume() { super.onResume(); io.execute { poller?.checkNow() } }