ThirdFactor Python SDK

Official server-side SDK for the ThirdFactor identity verification API.

Keep your ThirdFactor API key on the server. Never expose it in browser or mobile application code.

Installation

pip install thirdfactor-sdk

Python 3.9 or newer is supported. The SDK has no runtime dependencies.

Create a verification session

import os

from thirdfactor import ThirdFactor

tf = ThirdFactor(
    api_key=os.environ["THIRDFACTOR_API_KEY"],
    base_url="https://your-tenant.thirdfactor.ai",
)

session = tf.sessions.create(
    vendor_data="user-42",
    workflow_id="4c615aec-e173-450d-8089-30d4edc835f3",
    callback_url="https://example.com/kyc/done",
    idempotency_key="kyc-user-42",
)

print(session["url"])
decision = tf.sessions.decision(session["id"])

The workflow_id comes from GET /v3/workflows/:

workflows = tf.request("GET", "/v3/workflows/")

Verify webhooks

Webhook handlers must pass the untouched request bytes, before JSON parsing:

event = tf.webhooks.construct_event(raw_body, signature_header, "whsec_...")

Invalid or stale signatures raise SignatureError. The default replay window is five minutes.

Handle API errors

from thirdfactor import APIError

try:
    session = tf.sessions.retrieve("session-id")
except APIError as error:
    print(error.status, error.body, error.request_id)

See the ThirdFactor documentation for API, workflow, decision, and webhook details.