Liveness

The LIVENESS module proves there is a real, present human in front of the camera — defeating printed photos, screen replays, masks and deepfakes. It is a single module with a selectable method, configured on the workflow step (config.method). Liveness confirms a live human; it does not confirm the right human — that is Face Match, which nearly every real workflow runs alongside it.

Methods

Passive methods run through the standard capture step. The active methods (FLASHING, 3D_ACTION, GESTURE) issue a server-generated, single-use challenge — the applicant's client fetches the random sequence and submits the captured response to a dedicated verify endpoint. Because the sequence is random and server-issued, a pre-recorded replay of an earlier session fails.

Server enforcement

The configured method is enforced on the server — it cannot be downgraded or skipped from the client:

• The passive handler rejects a submission whose configured method is an active one (active_liveness_required) — active liveness has to arrive through the challenge/verify path, not as a passive frame.
• If a workflow requests a method the tenant is not entitled to, the engine falls back to PASSIVE rather than dropping liveness entirely — a downgrade to no-liveness is never the outcome.
• A required liveness module that never produced a terminal result forces the session to review, not approval — a skipped selfie can't pass as verified.

Choosing a method

• PASSIVE / PASSIVE_VIDEO for the highest conversion — the applicant barely notices it happened.
• 3D_ACTION / GESTURE when fraud pressure is real: account takeover, high-value accounts, injection-attack risk. The random challenge defeats replays.
• FLASHING as a middle ground — strong against printed photos and screen replays with almost no cognitive load.

How scoring and decisioning works

PASSIVE liveness produces a numeric score (0–100) that is compared against a per-workflow min_score (default 50 if the workflow doesn't set one). The terminal status is layered on top of that comparison, not just the raw number:

Common decline / review reasons

Sunglasses gate

By default liveness disallows sunglasses (config.disallow_sunglasses: true) — an ONNX classifier flags them so the applicant is asked to remove them, keeping the selfie usable for face match.

Camera requirements

Liveness needs camera access. In the web SDK, modal (iframe) mode requires the camera; microphone permissions policy (the SDK sets it and the flow serves it). On mobile browsers, camera in a cross-origin iframe is unreliable, which is why mode: "auto" opens a popup there. Behind a strict CSP, allow your Obsidian flow origin in frame-src, or use popup / redirect.

Result shape

LIVENESS returns a status and the method that ran, plus engine metadata. The raw liveness score threshold is an internal detail; the caller-facing signal is the terminal status. Read it from GET /v3/session/<id>/ or decision_v3.liveness_checks on the decision endpoint.

{
  "feature": "LIVENESS",
  "status": "approved",
  "score": 87.5,
  "warnings": [],
  "data": {
    "method": "PASSIVE",
    "engine": "thirdfactor-hosted",
    "age_gender": { "gender": "male" }
  }
}

curl -s "$TF_BASE_URL/v3/session/$SESSION_ID/" \
  -H "x-api-key: $TF_API_KEY" \
  | jq '.results[] | select(.feature == "LIVENESS")'

const session = await fetch(`${process.env.TF_BASE_URL}/v3/session/${sessionId}/`, {
  headers: { "x-api-key": process.env.TF_API_KEY! },
}).then((r) => r.json());
const liveness = session.results.find((r: any) => r.feature === "LIVENESS");
console.log(liveness.status, liveness.data.method);

import requests

session = requests.get(
    f"{BASE_URL}/v3/session/{session_id}/",
    headers={"x-api-key": API_KEY}, timeout=15,
).json()
liveness = next(r for r in session["results"] if r["feature"] == "LIVENESS")
print(liveness["status"], liveness["data"]["method"])

FAQ

Related