Python client for the FaceVault identity verification API — privacy-first KYC with liveness detection, face matching, and document verification.
- Sync & async clients — use
FaceVaultClientorAsyncFaceVaultClient - Webhook verification — HMAC-SHA256 signature validation
- Typed models — dataclasses for sessions, status, and webhook events
- Secure by default — HTTPS enforced, API keys validated, secrets redacted from logs
- Lightweight — only depends on httpx
pip install facevaultfrom facevault import FaceVaultClient
client = FaceVaultClient("fv_live_your_api_key")
# Create a verification session
session = client.create_session(external_user_id="user-123")
print(session.webapp_url) # Send this URL to your user
# With proof of address required
session = client.create_session(external_user_id="user-123", require_poa=True)
# Check session status
status = client.get_session(session.session_id)
print(status.status) # "in_progress", "passed", "failed", "review"
print(status.trust_score) # 0-100 trust score
print(status.trust_decision) # "accept", "review", "reject"
client.close()from facevault import AsyncFaceVaultClient
async def verify_user():
async with AsyncFaceVaultClient("fv_live_your_api_key") as client:
session = await client.create_session(external_user_id="user-123")
print(session.webapp_url)from facevault import verify_signature, parse_event
# Verify the webhook signature
body = request.body
signature = request.headers["X-FaceVault-Signature"]
if verify_signature(body, signature, secret="your_webhook_secret"):
event = parse_event(body)
print(event.event) # "verification.completed"
print(event.session_id)
print(event.face_match_passed)
print(event.trust_score) # 0-100
print(event.trust_decision) # "accept", "review", "reject"
print(event.sanctions_hit) # True/Falsefrom facevault import FaceVaultClient, AuthError, NotFoundError, RateLimitError
client = FaceVaultClient("fv_live_your_api_key")
try:
session = client.get_session("nonexistent")
except AuthError:
print("Invalid API key")
except NotFoundError:
print("Session not found")
except RateLimitError:
print("Too many requests")The SDK enforces security best practices out of the box:
- HTTPS only —
http://URLs are rejected at init to prevent credentials leaking over plaintext - Key validation — empty or whitespace-only API keys raise
ValueErrorimmediately - Secret redaction —
Session.__repr__maskssession_tokenand URL tokens, safe for logging - Client redaction —
FaceVaultClient.__repr__masks the API key - Path traversal protection —
get_session()validates session IDs
- Webhook signature verification now HMACs the raw request body instead of re-serializing the parsed JSON. The old approach couldn't reproduce the server's exact signed bytes for payloads containing non-ASCII characters (names, addresses) or whole-number floats, so valid webhooks could be silently rejected. Verification is now byte-exact — pass the body exactly as received.
- README + examples now document the webhook header as
X-FaceVault-Signature(the API has always sent this; v1.0.0 docs incorrectly showedX-Signature). - Reusable identity credentials (
/credentials/*) are noted in the Roadmap section — these are planned for the v2 SDK line alongside FacePass / FaceKey, not v1.x.
The FaceVault platform also offers reusable identity credentials ("verify once, prove forever" — credential challenge / verify / renew / status). These endpoints aren't wrapped by this SDK yet; they're planned for a future release. Until then, call them directly via the REST API.
See CONTRIBUTING.md. One topic per PR; update
CHANGELOG.md under ## [Unreleased].
Please do not open public issues for security vulnerabilities. See SECURITY.md or email security@facevault.id.
See CHANGELOG.md.
MIT — © Kaditham Holdings Pte Ltd