SDKs

SDK reference

The shared model behind every SDK — sessions and modes, configuration, and the full set of statuses, decisions and error codes. For calling verification steps directly over HTTPS, see the REST API guide instead.

Sessions & modes

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

Mode	How it works
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();

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

Field	Type	Description
`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.

Status	Meaning
`Created`	Session minted, not yet started.
`InProgress`	The user is actively verifying.
`Processing`	Evidence uploaded; backend is deciding.
`Completed`	Terminal — a decision is available.
`Expired`	Session passed its validity window.
`Failed`	Session 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.

Reason	Meaning
`close-button`	User tapped the built-in close control.
`backdrop / esc`	Web modal: backdrop click or Escape key.
`page-hide`	Web: the host page was unloaded.
`swipe-dismiss`	iOS: the sheet was pulled down to dismiss.
`back-button`	Android: system back navigation.
`host-destroy`	Your 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.

Code	Meaning
`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: UploadUrl, S3Put, ConfirmUpload.