Developer documentation

// Xcode ▸ File ▸ Add Package Dependencies… ▸ paste the repo URL (needs read access):
//   https://github.com/facededup/ios-sdk.git   → add product "FacededupLiveness"
// or in your app's Package.swift (use the 1.3.x STABLE line, NOT 2.0.0 alphas):
dependencies: [
    .package(url: "https://github.com/facededup/ios-sdk.git", from: "1.3.11"),
],
targets: [
    .target(name: "YourApp", dependencies: [
        .product(name: "FacededupLiveness", package: "ios-sdk")]),
]

// In your app's Package.swift — point a binaryTarget straight at S3.
// No git URL, no token: SPM downloads the zip and verifies the checksum.
targets: [
    .binaryTarget(
        name: "FacededupLiveness",
        url: "https://swiftend-assets-348761024048.s3.eu-west-2.amazonaws.com/sdk/ios/FacededupLiveness-1.3.11.xcframework.zip",
        checksum: "c53b3094a2d340b72374f5901a5d21b3778586580d37e1623aac64ee20333f79"
    ),
    .target(name: "YourApp", dependencies: ["FacededupLiveness"]),
]

// 1) Download + unzip (no auth):
//    https://swiftend-assets-348761024048.s3.eu-west-2.amazonaws.com/sdk/ios/FacededupLiveness-1.3.11.xcframework.zip
// 2) Drag FacededupLiveness.xcframework into your Xcode project.
// 3) Target ▸ General ▸ Frameworks, Libraries & Embedded Content →
//    set FacededupLiveness.xcframework to "Embed & Sign".
// That's it — no SPM, no CocoaPods, no GitHub.

import FacededupLiveness

let vc = FacededupVerificationController(config: .init(
    baseURL: URL(string: "https://facededup.ai")!,
    licenseKey: "fdk_…",       // per-tenant key (production auth); or password: "…" for the demo gate
    subjectId: "user-123"
)) { result in
    if result.passed {
        // verified — result.outcome / result.score / result.enrollmentId
    } else {
        // not verified — show result.outcome
    }
}
present(vc, animated: true)

import { LivenessClient, startCamera, grabFrame } from "@facededup/liveness-web";

const client = new LivenessClient({ baseUrl: "https://facededup.ai", licenseKey: "fdk_live_…" });
const video = document.querySelector("video")!;
const stop = await startCamera(video);                 // getUserMedia → <video>

const result = await client.run({
  subjectId: "user-123",
  signalScopes: ["device_signals", "precise_location"],  // user-consented scopes
  collect: { collectPreciseLocation: true, appVersion: "1.0.0" },
  capture: async (actions) => {
    // Drive YOUR UI through `actions` (e.g. ["blink","turn_left"]) and grab a
    // frame proving each. The server verifies the motion server-side.
    return actions.map((a) => grabFrame(video, a));
  },
});
stop();
console.log(result.outcome, result.is_live, result.score, result.signed_result?.token);

// npm i @facededup/liveness-react-native ; cd ios && pod install
import { startLiveness } from "@facededup/liveness-react-native";

const r = await startLiveness({
  baseUrl: "https://facededup.ai", subjectId: "user-123",
  licenseCert: "…",             // production auth
});
if (r.outcome === "captured" || r.is_live) {
  // upload r.selfie_image / r.liveliness_images / r.encrypted_payload
}

// pubspec: facededup_liveness ; cd ios && pod install
import 'package:facededup_liveness/facededup_liveness.dart';

final r = await FacededupLiveness.start(LivenessConfig(
  baseUrl: 'https://facededup.ai', subjectId: 'user-123',
  licenseCert: '…',
));
if (r.outcome == 'captured' || r.isLive) {
  // upload r.selfieImage / r.livelinessImages / r.encryptedPayload
}

// Capture the session on-device and keep the frames — no submit yet.
// Equivalent to "skip API submission": returns the captured payload.
verify.launch(FacededupConfig(
    baseUrl   = "https://facededup.ai",
    subjectId = "user-123",
    offlineMode = true,        // capture & store, don't submit
))
// result.passed is null while offline; result.raw holds the stored job id.

// Later, when the device is back online — submit the stored frames to the
// same /v1/verify endpoint. Server scores it; you get the signed result.
curl -u :PASSWORD -X POST https://facededup.ai/v1/verify   -H "Content-Type: application/json"   -d @stored-job.json
// → { "outcome": "live", "score": 0.95, "result_token": "…" }

{
  "subject_id": "user-123",
  "purpose": "nin_token_issuance_liveness",
  "lawful_basis": "consent",
  "channel": "web",
  "accepted": true
}

{ "consent_id": "cn_a1b2c3", "accepted": true, "recorded_at": "2026-06-13T12:00:00Z" }

{
  "subject_id": "user-123",
  "consent_id": "cn_a1b2c3",
  "method": "face_liveness",
  "risk_level": "baseline",
  "tenant_id": "harrys-living"
}

{ "request_id": "rq_77f0", "method": "face_liveness", "risk_level": "baseline" }

{ "request_id": "rq_77f0" }

{
  "session_id": "se_4d2",
  "nonce": "Yk3…q9",
  "actions": ["turn_left", "look_up", "turn_right"],
  "method": "face_liveness",
  "expires_at": "2026-06-13T12:00:20Z"
}

{
  "request_id": "rq_77f0",
  "session_id": "se_4d2",
  "nonce": "Yk3…q9",
  "frames": [
    { "image_b64": "<jpeg>", "proves_action": "turn_left" },
    { "image_b64": "<jpeg>", "proves_action": null }
  ],
  "audio_present": false,
  "attestation_token": "<Play Integrity / App Attest>",  // device attestation, verified server-side
  "illumination": { "responded": true, "delta": 34.0 },     // active-illumination reflection evidence
  "pad": { "screen_score": 0.04, "verdict": "genuine" }    // on-device screen/replay PAD
}

{
  "decision_id": "dc_9a1",
  "outcome": "live",            // live · referred · not_live
  "score": 0.95,
  "threshold": 0.6,
  "attestation_verified": true,
  "face_genuineness": "GENUINE",   // GENUINE · REPLAY_ATTACK · PRINT_ATTACK · SYNTHETIC_FACE · …
  "pad_gate": { "triggered": false, "reasons": [] },
  "result_token": "<ed25519-signed, 120s TTL>",
  "checks": [ { "name": "active_challenge", "passed": true } ]
}

{
  "id_type": "nin",             // "nin" | "bvn"
  "id_number": "12345678901",
  "selfie_b64": "<jpeg>",
  "result_token": "<from /v1/verify>"
}

{
  "found": true, "decision": "match", "match_score": 92.4,
  "full_name": "Ada N.", "date_of_birth": "1991-04-17",
  "id_number_masked": "*******8901", "source": "NIMC",
  "authority_photo_b64": "<jpeg>", "spoof": false
}

{ "selfie_b64": "<jpeg>", "result_token": "<from /v1/verify>" }

{ "mrz": "P<NGAADA<<…\nL898902C36NGA9001…" }

{
  "mrz": "P<NGA…",
  "document_photo_b64": "<id photo jpeg>",
  "selfie_b64": "<live selfie jpeg>",
  "chip_verified": false,
  "result_token": "<from /v1/verify>"
}

{
  "address": "12 Marina St, Lagos Island, Lagos",
  "lat": 6.4541, "lon": 3.3947,   // device GPS at the location
  "accuracy_m": 12,
  "subject_id": "user-123"
}

{
  "decision": "match",            // match · refer · no_match · not_found
  "formatted": "12 Marina St, Lagos Island…",
  "distance_m": 38.4,
  "match_radius_m": 150,
  "geocode": { "lat": 6.4538, "lon": 3.3949, "source": "google" },
  "decision_id": "…"
}

{
  "selfie_b64": "<jpeg>",
  "subject_id": "user-123",
  "tenant": "harrys-living",
  "country": "NG",
  "result_token": "<from /v1/verify — binds to a live face>"
}

{
  "enrollment_id": "FE-3A9B1B2260", "status": "enrolled",
  "live_verified": true,           // indexed into the gallery (live proof present)
  "dedup": { "decision": "no_match", "score": 41.2, "threshold": 62.0 }
}

{ "selfie_b64": "<jpeg>", "tenant": "harrys-living" }

{
  "decision": "duplicate",        // duplicate · refer · no_match
  "score": 94.1, "threshold": 62.0,
  "match": { "enrollment_id": "FE-…", "subject_id": "user-007", "similarity": 94.1 },
  "gallery_size": 1283
}

{ "token": "<result_token>" }   // 200 = valid & first use; 409 = already redeemed

# ECIES-P256 (recommended) — small/fast. Or RSA for legacy backends.
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out tenant.pem   # KEEP private
openssl pkey -in tenant.pem -pubout -outform DER | base64                        # SEND us this

FacededupConfig(baseUrl = BASE, subjectId = uid,
    licenseCert = "<your-cert>")   // verified offline + ENCRYPTS by default

FacededupConfig(baseURL: BASE, subjectId: uid,
    licenseCert: "<your-cert>")   // verified offline + ENCRYPTS by default

Step 3 — decrypt on your backend

Decrypt encryptedPayload with your private key (Python; mirror in Node/Java/Go). It decrypts to the canonical payload. Two schemes, chosen per-tenant by the cert: RSA-OAEP-256 or ECIES-P256 — both AES-256-GCM:

from cryptography.hazmat.primitives.asymmetric import padding, ec
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.kdf.hkdf import HKDF
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
import json, base64
def d(x): return base64.b64decode(x)

def decrypt(env, priv):                       # env = json.loads(encryptedPayload)
    if env["alg"].startswith("RSA"):
        k = priv.decrypt(d(env["enc_key"]),
            padding.OAEP(padding.MGF1(hashes.SHA256()), hashes.SHA256(), None))
    else:                                     # ECIES-P256
        epk = ec.EllipticCurvePublicKey.from_encoded_point(ec.SECP256R1(), d(env["epk"]))
        k = HKDF(hashes.SHA256(), 32, None, b"facededup-ecies-v1").derive(
                priv.exchange(ec.ECDH(), epk))
    return AESGCM(k).decrypt(d(env["iv"]), d(env["ciphertext"]) + d(env["tag"]), None)

Operator endpoints (Facededup-side, header X-License-Admin-Key) — how certs are minted/rotated/revoked; integrators don't call these:

{ "tenant_id": "acme", "enc_pubkey": "<your SPKI DER, base64>",
  "enc_alg": "ECIES-P256", "bundle_ids": ["com.acme.kyc"], "ttl_days": 60 }
// 200 -> { "license_cert": "...", "key_id": "...", "tenant_id": "acme" }

During the additive rollout the cert is optional (validated + logged). Enforcement is switched on per-deployment when your tenants have certs.

Enterprise response encryption beta.36

Public-key response encryption so that only your backend can read the SDK's result — even if an attacker fully reverse-engineers the mobile app. The SDK only encrypts: it holds no private key, implements no decryption, and stores no long-term secret. This is independent of, and preferred over, the license-cert encryption above.

Architecture

• SDK (mobile): collects the final result (+ challenge / backend liveness / dedup results), serializes it, encrypts it to a backend PUBLIC key, returns only the ciphertext envelope.
• Backend (you): owns the PRIVATE key, decrypts, validates integrity, shows the result in your dashboard. The private key never leaves the backend.

Public-key sources & rotation

Returns the current backend public key the SDK encrypts to — rotation-aware via keyId, cached on device (offline-safe). Sources: REMOTE (this endpoint, default) · EMBEDDED (compiled into the SDK) · INTEGRATOR (you supply it).

// 200
{ "version":"2.0", "keyId":"e48a7ea62ab69d63",
  "publicKey":"<base64 SPKI DER>",
  "algorithm":{ "payload":"AES-256-GCM", "keyExchange":"RSA-4096" },
  "cacheMaxAgeSeconds":1800 }

Rotation: change the backend key any time — the SDK re-fetches after its cache TTL and stamps the new keyId. Keep the OLD private key decryptable for in-flight payloads via env SDK_ENC_PRIVATE_KEY_B64_<oldKid>. No SDK update needed.

Per-session keys (preferred)

With sessionKeys:true, the SDK first mints a per-verification ephemeral keypair and encrypts to THAT — minimising the blast radius of any single key. The private key lives only on the backend (TTL'd) and is used once at decrypt, then expires.

// POST {} -> 200
{ "version":"2.0", "sessionId":"…", "keyId":"…",
  "publicKey":"<base64 SPKI>", "algorithm":{…}, "expiresAt":1750000000 }

Encrypted payload (what the SDK returns)

Default: encryptedPayload is a single opaque token — one base64 string with no field names and no algorithm label, so the result never telegraphs the scheme. The keyId, iv and tag still travel (decryption needs them) but as unlabeled bytes; the backend infers the algorithm from the key. Just paste the whole string into the console Decrypt result tool or POST it to /v1/sdk/decrypt.

"encryptedPayload": "9k3Jd…<one opaque base64 blob>…=="

The decrypt endpoints also accept the readable JSON envelope below (back-compat). The encrypted plaintext wraps integrity metadata (version, sessionId, transactionId, sdkVersion, nonce, timestamp), so a single AES-GCM tag protects both the result and its anti-tamper / anti-replay fields:

{
  "version": "2.0",
  "sessionId": "…",
  "keyId": "…",
  "algorithm": { "payload": "AES-256-GCM", "keyExchange": "RSA-4096" },
  "encryptedKey": "<RSA-OAEP-256 wrapped AES key>",
  "iv": "…", "tag": "…",
  "payload": "<base64 AES-256-GCM ciphertext>"
}

EC keys carry epk (ephemeral public point) instead of encryptedKey.

Backend decryption

Decrypt + integrity-validate an envelope (dashboard / back-office, admin-gated by X-Sdk-Admin-Key). Or decrypt with your own private key — the envelope is standard hybrid RSA-OAEP-SHA256 + AES-256-GCM. The backend rejects modified payloads (bad tag), replays (nonce reuse), expired sessions, clock-skew beyond the window, and unknown keyIds.

# POST the envelope, admin header -> 200
{ "valid": true, "result": { … the decrypted JSON … }, "meta": { "sdkVersion", "nonce", "timestamp", … } }

# Or decrypt yourself (Python):
from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
import base64, json
b = lambda x: base64.b64decode(env[x])
aes = priv.decrypt(b("encryptedKey"), padding.OAEP(padding.MGF1(hashes.SHA256()), hashes.SHA256(), None))
pt  = AESGCM(aes).decrypt(b("iv"), b("payload") + b("tag"), None)
result = json.loads(pt)["result"]

SDK configuration

// iOS (Swift)
FacededupConfig(baseURL: "https://facededup.ai", subjectId: "user-123",
  security: SecurityConfig(responseEncryption: true,
                          publicKeySource: .remote,   // .embedded / .integrator
                          cachePublicKey: true, cacheDurationMinutes: 30,
                          sessionKeys: false))

// Android (Kotlin)
FacededupConfig(baseUrl = "https://facededup.ai", subjectId = "user-123",
  security = SecurityConfig(responseEncryption = true,
                            publicKeySource = SecurityConfig.KeySource.REMOTE,
                            cachePublicKey = true, cacheDurationMinutes = 30,
                            sessionKeys = false))

When on, the SDK returns ONLY encryptedPayload (the v2 envelope) — payloadJson, images and metadata are nil/empty; outcome/errorCode stay cleartext for host flow. If encryption can't complete (and no cached/embedded key), the result fails closed with errorCode = device… encryption_failed — never cleartext.

Backend setup

Provision the master private key (you set it; it is never committed): ./scripts/setup-sdk-encryption-key.sh generates an RSA-4096 keypair. Because an RSA-4096 key is too large for a Lambda env var, store it in SSM Parameter Store (SecureString) and point the backend at it with SDK_ENC_PRIVATE_KEY_SSM (the Lambda role needs ssm:GetParameter + kms:Decrypt). Smaller EC keys may instead use the SDK_ENC_PRIVATE_KEY_B64 env var directly. For per-session keys across Lambda containers, create a DynamoDB table (PK session_id, TTL ttl) and set SDK_SESSION_KEY_TABLE.

Security switchboard

Inspect or toggle the enforcement gates. enforced gates can fail a verify; advisory gates report only.

Errors

Release notes

Facededup · API v1 · this page is static and safe to share.