Developer reference

11FaceID API

A small REST surface for enrollment, 1:1 identity verification, secure QR token lifecycle, and audit history. Requests and responses are JSON. No facial images are stored — only encrypted feature templates.

Verification engine

This build ships with a deterministic mock engine so the full workflow runs end-to-end without hardware. The engine lives behind a stable interface (detectFace, checkLiveness, extractFaceTemplate, compareTemplates) in src/lib/engine.ts, so the production Ainuverse SDK can be dropped in without changing the API contracts or UI.

POST/api/enroll

Enroll an identity for your tenant. The captured face is processed in memory, a feature template is extracted and encrypted, and only the encrypted template is stored — the image is discarded. Issues the first secure QR token.

Requires Authorization: Bearer <api key> — get a key from Settings → API Keys. The tenant is derived from the key.

Request

{
  "useCase": "event",
  "fullName": "Amelia Stone",
  "phone": "+1 555 0100",
  "email": "amelia@example.com",
  "fields": { "ticketId": "TKT-4821", "eventName": "Northwind Summit" },
  "faceImage": "data:image/jpeg;base64,…"   // processed then discarded
}

Response

{
  "id": "FID-A1B2C3",
  "status": "pending",
  "verifyUrl": "/verify/<signed-token>",
  "qr": { "version": 1, "status": "active", "expiresAt": "…" },
  "registration": { "id": "FID-A1B2C3", "faceTemplate": { "dim": 512, "alg": "AES-256-GCM" } }
}

POST/api/verify

Run a 1:1 verification. Supply the secure QR token (preferred) or a registration id for an operator-initiated check. The live face is processed in memory, liveness is checked, and the live template is compared against the stored encrypted template. Expired / revoked / cross-tenant attempts are blocked and audit-logged.

Request

{
  "token": "<signed-qr-token>",          // or "id": "FID-A1B2C3"
  "liveImage": "data:image/jpeg;base64,…" // processed then discarded
}

Response

{
  "liveness": "pass",
  "face_match": "pass",
  "match_score": 0.91,
  "decision": "approved",
  "reason": "Live face matched the enrolled template.",
  "timestamp": "…",
  "tenant_id": "tnt_event_northwind",
  "registration_id": "FID-A1B2C3"
}

POST/api/search

1:N search — an opt-in add-on (off by default). Matches a live frame against every enrolled face in your tenant's gallery instead of one claimed identity. Returns 403 until the tenant has explicitly enabled it. Disabling it immediately erases the separate plaintext embedding copy this feature requires.

Requires Authorization: Bearer <api key> — get a key from Settings → API Keys. The tenant is derived from the key.

Request

{
  "liveImage": "data:image/jpeg;base64,…",  // processed then discarded
  "top": 5                                   // optional, default 5
}

Response

{
  "count": 1,
  "matches": [
    { "registrationId": "FID-A1B2C3", "fullName": "Amelia Stone", "score": 0.81 }
  ]
}

GET/api/users/{id}

Fetch an enrolled identity profile. Returns template metadata only (dimensionality and algorithm) — never the raw template material or any image.

Response

{
  "id": "FID-A1B2C3",
  "tenantId": "tnt_event_northwind",
  "useCase": "event",
  "fullName": "Amelia Stone",
  "fields": { "ticketId": "TKT-4821" },
  "faceTemplate": { "templateId": "tpl_…", "dim": 512, "alg": "AES-256-GCM" },
  "status": "checked_in"
}

GET/api/verifications

Verification history — successful, failed, and blocked attempts. Optional ?tenantId= and ?registrationId= filters.

Response

{
  "count": 42,
  "verifications": [
    { "type": "verify", "decision": "approved", "matchScore": 0.91, "timestamp": "…" },
    { "type": "verify_blocked", "block": "qr_expired", "timestamp": "…" }
  ]
}

POST/api/qr/revoke

Revoke the active secure QR token for a registration. Subsequent verification attempts with that token are blocked and logged.

Request

{ "registrationId": "FID-A1B2C3" }

Response

{ "ok": true, "registrationId": "FID-A1B2C3", "status": "revoked" }

POST/api/qr/reissue

Issue a fresh secure QR token, superseding any prior active token (its version increments). Returns the new verify URL.

Request

{ "registrationId": "FID-A1B2C3" }

Response

{
  "ok": true,
  "registrationId": "FID-A1B2C3",
  "verifyUrl": "/verify/<new-signed-token>",
  "qr": { "version": 2, "status": "active" }
}

Optional module

Session Assurance

Continuous, policy-driven assurance throughout a session. These endpoints are available only when the module is enabled; otherwise they return 403. Organizations can define multiple Verification Policies and assign different policies to different workflows without changing the verification engine.

GET/api/session-policies

List Verification Policies and the available presets (Online Auction, Online Examination, Online Training, Remote Attendance). A preset is a recommended starting configuration only.

Response

{
  "policies": [ { "id": "pol_online_auction", "name": "Online Auction / Bidder Monitoring", "custom": false } ],
  "presets": [ { "key": "online_auction", "name": "Online Auction / Bidder Monitoring" } ]
}

POST/api/session-policies

Create a Verification Policy (Save as Custom Policy / Duplicate).

Request

{
  "name": "Exam — Final",
  "verification": { "intervalSecs": 45, "randomized": true, "matchThreshold": 0.78, "maxConsecutiveMismatches": 3, "maxMissedVerifications": 2 },
  "camera": { "disconnectedTimeoutSecs": 10, "blockedDetection": true, "unavailableAction": "require_reverify" },
  "response": { "onVerificationFailure": "require_reverify", "onMaxConsecutiveMismatches": "flag", "onMaxMissedVerifications": "flag" },
  "auditLevel": "full_history"
}

Response

{ "ok": true, "policy": { "id": "pol_…", "custom": true } }

PUT/api/session-policies/{id}

Edit an existing Verification Policy.

Request

{ "verification": { "intervalSecs": 60 } }

Response

{ "ok": true, "policy": { "id": "pol_…", "updatedAt": "…" } }

DELETE/api/session-policies/{id}

Delete a Verification Policy. Blocked (409) while referenced by a live session.

Response

{ "ok": true, "id": "pol_…", "status": "deleted" }

POST/api/sessions/start

Start a Session Assurance session for an enrolled identity under a selected policy. Records an initial 1:1 verification.

Request

{ "registrationId": "FID-D4E5F6", "policyId": "pol_online_auction" }

Response

{ "ok": true, "session": { "id": "ses_…", "status": "active", "totalChecks": 1 } }

POST/api/sessions/check

Run one periodic identity verification. Frames are processed in memory only. Optional flags simulate a missed check or a camera problem; the policy decides the response.

Request

{ "sessionId": "ses_…", "kind": "scheduled" }   // or { "missed": true } / { "camera": "lost" }

Response

{ "ok": true, "session": { "status": "warning", "failedChecks": 1, "consecutiveMismatches": 1 } }

POST/api/sessions/reverify

Perform an immediate re-verification. On success the session returns to active; on failure it escalates per the policy.

Request

{ "sessionId": "ses_…" }

Response

{ "ok": true, "session": { "status": "active" } }

POST/api/sessions/end

End a session and write the closing audit event.

Request

{ "sessionId": "ses_…" }

Response

{ "ok": true, "session": { "status": "completed", "endedAt": "…" } }

GET/api/sessions

List assurance sessions (optional ?tenantId= scope).

Response

{ "count": 1, "sessions": [ { "id": "ses_…", "policyName": "Online Auction / Bidder Monitoring", "status": "active" } ] }