End-to-End Encryption

End-to-end encryption (E2EE) adds a second layer of encryption on top of HTTPS so that any intermediary that terminates TLS — corporate proxy, CDN, transparent firewall, attacker MITM with a trusted root — cannot read PII payloads (selfie images, ID photos, identity fields). The SDK exposes it as a single opt-in flag on setup().

Warning

E2EE must be provisioned for your account on the back end. Until it is, flipping encryption: true against a regular apiURL fails initialization at setup() and the SDK throws. Contact your Incode representative.

What you'll get from your Incode account team

When E2EE is enabled for your account, your account team will provide:

A dedicated apiURL. E2EE traffic is served from a different host than the regular API (typically *-e2ee-api.incodesmile.com). Pointing encryption: true at your standard apiURL fails initialization. The MGF1 scheme the environment expects — 'sha1' (default; matches most existing Incode environments) or 'sha256' (some environments are explicitly provisioned for it). Confirm both values before you start. They are dictated by the environment, not by you.

Minimum integration

Two lines of setup() flip E2EE on:

import { setup } from '@incodetech/core';

await setup({
  apiURL: 'https://<your-incode-e2ee-host>/0', // see "API key transmission" below
  encryption: true,
});

The SDK initializes encrypted transport during setup(). Treat the session token returned by createSession() as an opaque string.

API key transmission

Use the complete apiURL and authentication configuration supplied by your Incode account team. For session-based integrations, the provisioned URL can include a /0 suffix. Keep that suffix when instructed. Some environments instead require an x-api-key custom header; confirm the required integration form before deployment.

Do not embed production API keys in browser code. Confirm the supported browser authentication arrangement with your account team.

MGF1 scheme

encryption accepts a boolean shorthand or an object form with mgf1:

// Default — MGF1 = SHA-1 (matches most existing Incode environments)
await setup({
  apiURL: 'https://<your-incode-e2ee-host>/0',
  encryption: true,
});

// Pin SHA-256 — only when your environment is provisioned for it
await setup({
  apiURL: 'https://<your-incode-e2ee-host>/0',
  encryption: { mgf1: 'sha256' },
});

encryption: true is equivalent to encryption: {}. Both enable encryption with the SHA-1 default.

The mgf1 value must match what the environment expects. A mismatch causes encrypted requests to fail. Confirm the value with your account team.

Constraints

Requires the binary (WASM) transport. setup({ wasm: false, encryption: true }) throws. Either omit wasm (the SDK provisions the binary transport with CDN defaults automatically) or pass a WasmConfig object alongside encryption: true. See WASM Configuration.
Independent of token. Encryption can be configured before a session token is available.
Locked at boot. The first setup() call decides whether encryption is on and which mgf1 scheme is used. Subsequent setup() calls that would change either value throw. Call reset() first if you genuinely need to switch.
Required by on-device face capture. Selfie / Authentication's onDeviceFaceResultsSubmissionEnabled: true only works against the E2EE-provisioned host. See On-Device Face Capture.

Initialization failures

If initialization fails, setup() rejects with a descriptive error. There is no built-in retry — catch the error and re-call setup() (after reset() if needed) when your environment is known-flaky.

Symptom	Likely cause	Fix
`setup()` rejects with an initialization error	apiURL unreachable	Verify network / DNS, retry.
Same, on a known-good network	Environment not provisioned for E2EE	Reach out to your Incode account team. Confirm you're using the E2EE host they provided.
Encrypted requests fail after initialization	mgf1 mismatch with what the env expects	Confirm the expected scheme with your contact, pass encryption: `{ mgf1: 'sha256'}` (or 'sha1').
Requests fail to identify the tenant	Missing API key	Confirm the provisioned URL and authentication configuration. See "API key transmission".
`setup({ encryption: ... })` throws on a re-call	Encryption is locked at boot	Call `reset()` first.
`setup({ wasm: false, encryption: true })` throws	Encryption requires the WASM binary transport	Omit `wasm: false`, or pass a `WasmConfig` object alongside `encryption: true`.

Full example: self-hosted WASM + E2EE

await setup({
  apiURL: 'https://<your-incode-e2ee-host>/0',
  encryption: { mgf1: 'sha256' }, // whichever your env expects
  wasm: {
    wasmPath: '/wasm/webLib.wasm',
    glueCodePath: '/wasm/webLib.js',
    modelsBasePath: '/wasm/models',
  },
});