Didit Liveness Detection

Detects liveness from a single selfie image via the Didit standalone API. Use when checking if a person is physically present, detecting spoofing or presenta...

Security Scan

The skill's code, instructions, and requested credential (DIDIT_API_KEY) are consistent with a liveness-detection client that calls the Didit standalone API; no incoherent or unrelated privileges are requested.

Purpose & Capability

Name and description match the implemented behavior: SKILL.md documents a passive-liveness API and the included Python script posts a user image to the documented Didit endpoint using x-api-key. The single required env var (DIDIT_API_KEY) is exactly what the API needs.

Instruction Scope

Instructions only describe sending one user image and optional parameters to the Didit endpoint. They do, however, advertise additional platform features (blocklist matching, duplicate detection, saving API requests) and the docs indicate that requests may be persisted by default (save_api_request default = true). This is expected for a third-party biometric API but is a privacy/retention concern (the skill will transmit raw biometric images to Didit).

Install Mechanism

There is no install spec (instruction-only), which minimizes supply-chain risk. The included Python script uses the 'requests' package but the SKILL.md does not list dependencies or installation instructions — the runtime must provide Python and the requests library or the script will fail.

Credentials

Only one credential is required: DIDIT_API_KEY (declared as primary). That matches the documented API authentication (x-api-key). No unrelated credentials, files, or system paths are requested.

Persistence & Privilege

Skill is not always-enabled and does not request system or cross-skill configuration. It does not modify other skills or system settings. The primary persistence concern is external (Didit storing submitted images/requests), not local agent privileges.

Assessment

This skill is coherent with its stated purpose, but it sends raw biometric images to an external service. Before installing, confirm you trust Didit and that sending user selfies to their API meets your privacy, legal, and data-retention requirements (the docs indicate API requests may be saved by default). Ensure the runtime has Python and the 'requests' library available. Protect DIDIT_API_KEY like any secret (store it securely and limit its scope/rotation). If you need to avoid uploading images to a third party, use an on-device or self-hosted solution instead. Finally, review Didit's privacy and retention policies and confirm whether 'blocklist' or duplicate-detection features could impact user rights in your jurisdiction.

Didit Passive Liveness API

Overview

Verifies that a user is physically present by analyzing a single captured image — no explicit movement or interaction required.

Key constraints:

• Supported formats: JPEG, PNG, WebP, TIFF
• Maximum file size: 5MB
• Image must contain exactly one clearly visible face
• Original real-time photo only (no screenshots or printed photos)

Accuracy: 99.9% liveness detection accuracy, <0.1% false acceptance rate (FAR).

Capabilities: Liveness scoring, face quality assessment, luminance analysis, age/gender estimation, spoof detection (screen captures, printed copies, masks, deepfakes), duplicate face detection across sessions, blocklist matching.

Liveness methods: This standalone endpoint uses PASSIVE method (single-frame CNN). Workflow mode also supports ACTIVE_3D (action + flash, highest security) and FLASHING (3D flash, high security).

API Reference: https://docs.didit.me/standalone-apis/passive-liveness Feature Guide: https://docs.didit.me/core-technology/liveness/overview

---

Authentication

All requests require x-api-key header. Get your key from Didit Business Console → API & Webhooks, or via programmatic registration (see below).

Getting Started (No Account Yet?)

If you don't have a Didit API key, create one in 2 API calls:

1. Register: POST https://apx.didit.me/auth/v2/programmatic/register/ with {"email": "[e-mail]", "password": "MyStr0ng!Pass"}
2. Check email for a 6-character OTP code
3. Verify: POST https://apx.didit.me/auth/v2/programmatic/verify-email/ with {"email": "[e-mail]", "code": "A3K9F2"} → response includes api_key

To add credits: GET /v3/billing/balance/ to check, POST /v3/billing/top-up/ with {"amount_in_dollars": 50} for a Stripe checkout link.

See the didit-verification-management skill for full platform management (workflows, sessions, users, billing).

---

Endpoint

POST https://verification.didit.me/v3/passive-liveness/

Headers

Header	Value	Required
x-api-key	Your API key	Yes
Content-Type	multipart/form-data	Yes

Request Parameters (multipart/form-data)

Parameter	Type	Required	Default	Constraints	Description
user_image	file	Yes	—	JPEG/PNG/WebP/TIFF, max 5MB	User's face image
face_liveness_score_decline_threshold	integer	No	—	0-100	Scores below this = Declined
rotate_image	boolean	No	—	—	Try rotations to find upright face
save_api_request	boolean	No	true	—	Save in Business Console
vendor_data	string	No	—	—	Your identifier for session tracking

Example

import requests

response = requests.post(
    "https://verification.didit.me/v3/passive-liveness/",
    headers={"x-api-key": "YOUR_API_KEY"},
    files={"user_image": ("selfie.jpg", open("selfie.jpg", "rb"), "image/jpeg")},
    data={"face_liveness_score_decline_threshold": "80"},
)

const formData = new FormData();
formData.append("user_image", selfieFile);
formData.append("face_liveness_score_decline_threshold", "80");

const response = await fetch("https://verification.didit.me/v3/passive-liveness/", {
  method: "POST",
  headers: { "x-api-key": "YOUR_API_KEY" },
  body: formData,
});

Response (200 OK)

{
  "request_id": "a1b2c3d4-...",
  "liveness": {
    "status": "Approved",
    "method": "PASSIVE",
    "score": 95,
    "user_image": {
      "entities": [
        {"age": 22.16, "bbox": [156, 234, 679, 898], "confidence": 0.717, "gender": "male"}
      ],
      "best_angle": 0
    },
    "warnings": [],
    "face_quality": 85.0,
    "face_luminance": 50.0
  },
  "created_at": "2025-05-01T13:11:07.977806Z"
}

Status Values & Handling

Status	Meaning	Action
"Approved"	User is physically present	Proceed with your flow
"Declined"	Liveness check failed	Check warnings. May be a spoof or poor image quality

Error Responses

Code	Meaning	Action
400	Invalid request	Check file format, size, parameters
401	Invalid API key	Verify x-api-key header
403	Insufficient credits	Top up at business.didit.me

---

Response Field Reference

Field	Type	Description
status	string	"Approved" or "Declined"
method	string	Always "PASSIVE" for this endpoint
score	integer	0-100 liveness confidence (higher = more likely real). null if no face
face_quality	float	0-100 face image quality score. null if no face
face_luminance	float	Face luminance value. null if no face
entities[].age	float	Estimated age
entities[].bbox	array	Face bounding box [x1, y1, x2, y2]
entities[].confidence	float	Face detection confidence (0-1)
entities[].gender	string	"male" or "female"
warnings	array	{risk, log_type, short_description, long_description}

---

Warning Tags

Auto-Decline (always)

Tag	Description
NO_FACE_DETECTED	No face detected in image
LIVENESS_FACE_ATTACK	Potential spoofing attempt (printed photo, screen, mask)
FACE_IN_BLOCKLIST	Face matches a blocklisted entry
POSSIBLE_FACE_IN_BLOCKLIST	Possible blocklist match detected

Configurable (Decline / Review / Approve)

Tag	Description	Notes
LOW_LIVENESS_SCORE	Score below threshold	Configurable review + decline thresholds
DUPLICATED_FACE	Matches another approved session	—
POSSIBLE_DUPLICATED_FACE	May match another user	Configurable similarity threshold
MULTIPLE_FACES_DETECTED	Multiple faces (largest used for scoring)	Passive only
LOW_FACE_QUALITY	Image quality below threshold	Passive only
LOW_FACE_LUMINANCE	Image too dark	Passive only
HIGH_FACE_LUMINANCE	Image too bright/overexposed	Passive only

---

Common Workflows

Basic Liveness Check

1. Capture user selfie
2. POST /v3/passive-liveness/ → {"user_image": selfie}
3. If "Approved" → user is real, proceed
   If "Declined" → check warnings:
     - NO_FACE_DETECTED → ask user to retake with face clearly visible
     - LOW_FACE_QUALITY → ask for better lighting/positioning
     - LIVENESS_FACE_ATTACK → flag as potential fraud

Liveness + Face Match (combined)

1. POST /v3/passive-liveness/ → verify user is real
2. If Approved → POST /v3/face-match/ → compare selfie to ID photo
3. Both Approved → identity verified

---

Utility Scripts

export DIDIT_API_KEY="your_api_key"

python scripts/check_liveness.py selfie.jpg
python scripts/check_liveness.py selfie.jpg --threshold 80