Client / Widget API
The surface the in-browser widget uses to drive a single session.
Base: /api/v1/client · Auth: X-Client-Token: <token> (or Authorization: Bearer <token>)
Tokens
The client_token from POST /v1/sessions is a single-use launch token. It authorizes one call: POST /v1/client/claim, which returns this browser's device token. Every other endpoint takes the device token.
- A launch token can be claimed once. A second claim returns
409 client_token_used, so a leaked link is useless after the user opens it. - A device token is bound to the
Originit was claimed from; the same token from another origin returns403 origin_not_allowed. - Both expire with the session.
- For cross-device handoff,
POST /v1/client/handoffmints a single-use handoff token for the QR code. The other device claims it for its own device token. Only the newest handoff token is valid.
The widget does all of this for you, and keeps the device token in localStorage until the session expires, so a reload continues the session.
POST /api/v1/client/claim
X-Client-Token: <launch or handoff token>
201 { "data": { "token": "<device token>", "expires_at": "…" } }WARNING
You normally don't call these endpoints directly; the widget does. They're documented for custom flows.
Endpoints
| Method | Path | Description |
|---|---|---|
POST | /v1/client/claim | Exchange a launch or handoff token for this browser's device token. |
POST | /v1/client/handoff | Mint a single-use handoff token for the cross-device QR code. |
GET | /v1/client/session | Fetch the session; marks it started on first load. |
POST | /v1/client/document/front | Submit the document front; runs OCR + portrait extraction. |
POST | /v1/client/document/back | Submit the document back (skipped for single-sided docs). |
POST | /v1/client/liveness | Submit the selfie / passive liveness frame. |
POST | /v1/client/address | Submit the claimed address (only when the workflow enables the address stage). |
POST | /v1/client/complete | Finalize: run the decision engine and land the verdict. |
Uploads
Document and liveness endpoints accept multipart/form-data with the image file. With mock providers you may include hint fields to script the outcome (e.g. confidence, expired, score, passed, similarityScore); see Provider drivers.
POST /api/v1/client/document/front
X-Client-Token: <token>
Content-Type: multipart/form-data
image=@front.jpgAddress
When the workflow enables the address stage, submit the claimed address fields (multipart/form-data). Depending on the configured methods, include a poa proof-of-address image and/or device latitude / longitude. With mock, the address_score / address_passed hints script the outcome.
POST /api/v1/client/address
X-Client-Token: <token>
Content-Type: multipart/form-data
line1=31 Gwarri Avenue
city=Kaduna
country=NG
latitude=10.48342
longitude=7.43488Completing
POST /api/v1/client/complete
X-Client-Token: <token>Enqueues the biometric + decision work (or runs inline with the sync queue). The session moves to processing, then to approved / requires_review / rejected. Read the result via the Public API or a webhook.
Limits
- Sessions expire (default 15 minutes); expired sessions reject further calls.
- Liveness is capped at 3 attempts per session.
