Skip to content

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 Origin it was claimed from; the same token from another origin returns 403 origin_not_allowed.
  • Both expire with the session.
  • For cross-device handoff, POST /v1/client/handoff mints 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.

http
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 ​

MethodPathDescription
POST/v1/client/claimExchange a launch or handoff token for this browser's device token.
POST/v1/client/handoffMint a single-use handoff token for the cross-device QR code.
GET/v1/client/sessionFetch the session; marks it started on first load.
POST/v1/client/document/frontSubmit the document front; runs OCR + portrait extraction.
POST/v1/client/document/backSubmit the document back (skipped for single-sided docs).
POST/v1/client/livenessSubmit the selfie / passive liveness frame.
POST/v1/client/addressSubmit the claimed address (only when the workflow enables the address stage).
POST/v1/client/completeFinalize: 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.

http
POST /api/v1/client/document/front
X-Client-Token: <token>
Content-Type: multipart/form-data

image=@front.jpg

Address ​

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.

http
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.43488

Completing ​

http
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.

Released under the MIT License.