Core concepts

Verification

One end-to-end identity check for one person. Identified by a sortable, globally unique ID (ver_…) that you store and use everywhere — status polling, attestations, erasure. Lifecycle:

created → doc_uploaded → processing → approved | rejected | manual_review

Manual review resolves to approved or rejected via the review queue.

The two credential tiers

This split is the core of the security model — understand it and the rest follows.

Credential	Held by	Can do	Cannot do
API key	Your backend only	Create verifications, read results, issue attestations, erase data, work the review queue	—
Handoff token	The user’s device, for ≤30 min	Upload captures for one verification, see its bare status (created/processing/…)	Read any extracted identity data, touch any other verification, do anything after expiry/revocation

A phished or leaked handoff token is nearly worthless: it exposes no PII and dies in minutes. This is why the QR/deep-link handoff is safe to render in a browser.

Artifacts and the vault

Every capture (ID photos, selfie frames) and the AI’s full extraction output are artifacts: encrypted individually with their own AES-256-GCM key the moment they arrive, stored in the vault, and referenced from the database only by hash and path. The operational database never contains images or document numbers.

Challenge (active liveness)

A short random pose sequence (always starting center, then random left/right turns) issued per verification. The device uploads one frame per step; the pipeline verifies head pose per frame and that every frame shows the same person. A printed photo can’t turn its head; a pre-recorded video won’t match a random sequence; swapping faces mid-challenge trips identity-consistency detection.

Decision

The pipeline’s structured verdict: a status plus human-readable decision_reasons (every reason is also an auditable event). The engine is fail-safe: uncertainty never auto-approves — see Fraud signals for the full signal → outcome mapping.

Attestation

An Ed25519-signed token (JWT-shaped) asserting selected claims — verified, over_18, name, date_of_birth, document_country — about an approved verification. Consumers verify it offline against the service’s public key. This is how other systems learn “this person is verified” without receiving identity data.

Audit chain

An append-only log where each event includes the SHA-256 hash of the previous event. Every material action — creation, uploads, challenge issuance, decisions, reviewer actions, attestations, erasure — is chained. Rewriting history breaks the chain detectably; this is your evidence trail for disputes and regulators.