Metadata-Version: 2.4
Name: thirdfactor-sdk
Version: 0.1.0
Summary: Official server-side SDK for ThirdFactor
Author-email: ThirdFactor <support@thirdfactor.ai>
License-Expression: MIT
Project-URL: Documentation, https://docs.v3.thirdfactor.ai
Project-URL: Homepage, https://thirdfactor.ai
Keywords: thirdfactor,kyc,identity,verification
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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

```bash
pip install thirdfactor-sdk
```

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

## Create a verification session

```python
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/`:

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

## Verify webhooks

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

```python
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

```python
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](https://docs.v3.thirdfactor.ai) for API,
workflow, decision, and webhook details.
