Metadata-Version: 2.4
Name: ontiver
Version: 0.1.0
Summary: Official Python SDK for the Ontiver API
Author: Ontiver
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://ontiver.com
Project-URL: Documentation, https://docs.ontiver.com
Project-URL: Repository, https://github.com/joinverza/Ontiver
Keywords: ontiver,kyc,aml,identity,proofs,webhooks
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx<1,>=0.27
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Provides-Extra: build
Requires-Dist: build>=1.2; extra == "build"
Requires-Dist: twine>=5; extra == "build"

# Ontiver Python SDK

Official Python SDK for integrating Ontiver verification, screening, proofs, and webhooks into enterprise backends.

The dashboard remains the control plane for API keys, scopes, billing, team roles, webhooks, and audit logs. The SDK is the integration layer for Django, Flask, FastAPI, workers, and internal services.

## Install Locally

From this repository:

```bash
cd sdks/python
python -m pip install -e ".[test]"
```

After publication:

```bash
python -m pip install ontiver
```

## Configuration

Create an API key from the Ontiver enterprise dashboard and store it in your secret manager.

```bash
ONTIVER_API_KEY=prod_xxx
ONTIVER_BASE_URL=https://api.ontiver.com
ONTIVER_ENVIRONMENT=production
ONTIVER_WEBHOOK_SECRET=whsec_xxx
```

Use sandbox keys in non-production environments:

```bash
ONTIVER_API_KEY=sb_xxx
ONTIVER_ENVIRONMENT=sandbox
```

## Quickstart

```python
from ontiver import OntiverClient

client = OntiverClient.from_env()

startup_check = client.validate_api_key()
print(startup_check["valid"])
```

## Verification

SDK v1 routes flexible verification payloads to:

```text
POST /api/v1/banking/kyc/individual/verify
GET  /api/v1/banking/kyc/individual/{verificationId}
```

```python
result = client.verifications.create(
    {
        "customerId": "cust_123",
        "firstName": "Ada",
        "lastName": "Okafor",
        "country": "NG",
        "idDocumentType": "passport",
        "idDocumentNumber": "A12345678",
    },
    idempotency_key="verify-cust-123",
)

status = client.verifications.get(result["verificationId"])
```

## Screening

```python
screening = client.screening.sanctions_check(
    first_name="Ada",
    last_name="Okafor",
    nationality="NG",
    idempotency_key="sanctions-cust-123",
)
```

Supported methods:

- `client.screening.pep_check(...)`
- `client.screening.sanctions_check(...)`
- `client.screening.adverse_media_check(first_name, last_name, ...)`

## Proofs

```python
proof = client.proofs.get_for_verification("ver_123")

verified = client.proofs.verify(
    proof_id=proof["proofId"],
    proof=proof.get("proof"),
)
```

Supported methods:

- `client.proofs.generate(...)`
- `client.proofs.get_for_verification(verification_id)`
- `client.proofs.verify(proof_id, proof=None)`
- `client.proofs.disclose(proof_id, fields=[...])`

## Webhooks

Register a webhook:

```python
webhook = client.webhooks.register(
    "https://example.com/webhooks/ontiver",
    ["verification.completed", "proof.issued"],
)

# Store this once. It will not be returned by list endpoints.
secret = webhook["secret"]
```

Verify webhook signatures using the raw request body:

```python
from ontiver.webhooks import verify_webhook_signature

is_valid = verify_webhook_signature(raw_body, request.headers["X-Ontiver-Signature"], secret)
```

Header format:

```text
X-Ontiver-Signature: sha256=<hex_digest>
```

## Raw Request Escape Hatch

Use `raw_request()` for routes that do not have first-class wrappers yet:

```python
result = client.raw_request(
    "POST",
    "/aml/smile-checks",
    json={"fullName": "Ada Okafor", "countries": ["NG"]},
    idempotency_key="aml-cust-123",
)
```

## Errors

Catch specific exceptions:

```python
from ontiver import AuthenticationError, PermissionDeniedError, RateLimitError, ValidationError

try:
    client.validate_api_key()
except AuthenticationError:
    ...
except PermissionDeniedError:
    ...
except RateLimitError:
    ...
except ValidationError:
    ...
```

The SDK redacts API keys, bearer tokens, webhook secrets, and secret prefixes from exception messages.

## Security Notes

- Never commit API keys or webhook secrets.
- Store production secrets in a secret manager.
- Use least-privilege API key scopes.
- Use sandbox keys outside production.
- Verify webhook signatures over the raw body bytes before parsing JSON.
- Do not log raw identity documents, ID numbers, biometric payloads, or full provider payloads.

## Build And Publish

Build locally:

```bash
cd sdks/python
python -m pip install -e ".[test]"
pytest
python -m pip install ".[build]"
python -m build
python -m twine check dist/*
```

Publish first to TestPyPI:

```bash
python -m twine upload --repository testpypi dist/*
```

Install from TestPyPI in a clean environment:

```bash
python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple ontiver
```

Publish to PyPI after TestPyPI install passes:

```bash
python -m twine upload dist/*
```

Target package name: `ontiver`.
