Platform

API reference

The shared model behind every SDK — sessions and modes, webhooks, configuration, and the full set of statuses, decisions and error codes.

Sessions & modes

A session is one run of a workflow for one user. There are two ways to start one:

Create mode

The client configures the SDK with a public key, workflowExternalId and clientData. The SDK mints the session. Fastest to integrate.

Token mode

Your server mints a session and returns a sat to the client. No keys ever reach the device. Recommended for production.

token mode

// On YOUR server — never expose the secret to the client.
// 1. Create a session with your private credentials.
// 2. Return the session access token (sat) to your app.

// In the client SDK, start in token mode:
new OthentoSDK({
  mode: 'token',
  sat: '<session-access-token-from-your-server>',
  onCompleted: ({ decision }) => console.log(decision),
}).start();

Webhooks

When a session reaches a terminal decision, Othento can notify your backend at the callbackUrl you provide. Use callbackReceiver to choose which party is notified (Initiator, Completer or Both). Correlate the notification to your user with the session externalId (saved from onSessionCreated) and the clientData and metadata you passed in. Always treat the webhook — not the client callback — as the source of truth for granting access.

Session configuration

The same options across every SDK. Three fields are required to create a session.

Option	Type	Description
mode	'create' \| 'token'	Required. Create a new session (create) or resume a server-minted one (token).
apiKey	string · create	Public key. pk_sandbox_… for testing, pk_live_… for production.
workflowExternalId	string · create	The verification workflow this session runs.
clientData	string · create	Your end-user identifier; echoed on events and webhooks.
sat	string · token	Server-minted session access token; keeps API keys off the client.
expectedDetails	object · optional	Pre-filled identity hints cross-checked against extracted data.
callbackUrl	string · optional	Webhook / redirect URL for terminal session notifications.
callbackReceiver	'Initiator' \| 'Completer' \| 'Both'	Which party receives the callback. Optional.
metadata	string · optional	Free-form string round-tripped on session events and webhooks.

Web only: container (inline mode), showCloseButton, closeOnBackdropClick, loadTimeoutMs, initTimeoutMs. Mobile only: closeOnComplete, loggingEnabled (Android).

expectedDetails

Optional identity hints, cross-checked against extracted document data. Send only what you have.

firstName / lastName	string	Given and family name.
dateOfBirth	string	ISO-8601, e.g. 1990-04-23.
gender	string	Expected gender.
nationality / country	string	Expected nationality and country.
address	string	Expected address.
documentNumber	string	Expected document number.
ipAddress	string	End-user IP address.

Session statuses

Streamed through the status callback as the session progresses.

CreatedSession minted, not yet started.

InProgressThe user is actively verifying.

ProcessingEvidence uploaded; backend is deciding.

CompletedTerminal — a decision is available.

ExpiredSession passed its validity window.

FailedSession ended in a non-recoverable failure.

Decisions

The terminal outcome, returned by onCompleted.

Approved

Identity verified and approved.

Declined

Verification failed or was rejected.

InReview

Pending manual review.

Cancellation reasons

Returned by onCancelled — useful for adaptive retry UX and analytics.

close-buttonUser tapped the built-in close control.

backdrop / escWeb modal: backdrop click or Escape key.

page-hideWeb: the host page was unloaded.

swipe-dismissiOS: the sheet was pulled down to dismiss.

back-buttonAndroid: system back navigation.

host-destroyYour app called destroy() before a decision.

Error codes

Every error exposes a typed code you can switch on. When code is upload_failed, error.stage pinpoints the step.

missing_api_key	Required apiKey not provided (thrown at construction).
missing_workflow	Required workflowExternalId not provided.
missing_client_data	Required clientData not provided.
config_invalid	Other configuration validation failure.
camera_permission_denied	Camera blocked, or the web page is not on HTTPS.
session_not_found	The session id did not resolve.
session_expired	Session minted too long ago to start.
session_failed	Session ended in a failed state server-side.
session_token_expired	Token-mode SAT expired (mobile).
network	Transient connectivity failure; safe to retry.
create_failed	Session creation failed — check key and workflow.
documents_failed	Document capture or processing failed.
initiate_failed	Flow failed to start after session creation.
upload_failed	Evidence upload failed; see error.stage.
poll_failed	Polling for the result failed.
file_too_large	Captured file exceeded the upload limit.
iframe_load_failed	Web: the SDK iframe did not load in time.
init_timeout	Web: the ready handshake did not complete in time.
version_mismatch	Web: SDK / flow bridge protocol mismatch.
unknown	Unclassified runtime error.

upload_failed stages:UploadUrlS3PutConfirmUpload

Back to Quickstart →Get API keys