Metadata-Version: 2.4
Name: ontiver
Version: 0.1.6
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_API_SECRET=sec_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_API_SECRET=sec_xxx
ONTIVER_ENVIRONMENT=sandbox
```

Dashboard-created API keys include a one-time API secret. Store both values; authenticated requests send the key as `Authorization: Bearer ...` and the secret as `X-Ontiver-API-Secret`.

## Quickstart

```python
from ontiver import OntiverClient

client = OntiverClient.from_env()

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

Validate credentials without making mutating production calls:

```bash
ontiver-smoke
```

Async services can use the async client with the same resources:

```python
from ontiver import AsyncOntiverClient

async with AsyncOntiverClient.from_env() as client:
    startup_check = await client.validate_api_key()
    webhooks = await client.webhooks.list()
```

## High-Risk Request Options

Mutating enterprise actions that are nonce-protected or step-up protected accept the same security options:

```python
import time
import uuid

client.api_keys.revoke(
    "key_123",
    idempotency_key="revoke-key-123",
    nonce=str(uuid.uuid4()),
    timestamp=int(time.time()),
)
```

Supported options include `idempotency_key`, `nonce`, `timestamp`, `admin_step_up_token`, and `impersonation_token`.

## 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=[...])`
- `client.proofs.circuits()`
- `client.proofs.noir_toolchain()`
- `client.proofs.generate_noir(...)`
- `client.proofs.verify_noir(...)`

## Enterprise Disclosure Requests

```python
import time
import uuid

request = client.disclosure_requests.create(
    user_email="customer@example.com",
    verification_type="bvn",
    requested_fields=["verified_status", "full_name", "date_of_birth"],
    purpose="Account onboarding",
    audience="Ontiver demo",
    challenge="customer-session-123",
    ttl_minutes=60,
    nonce=str(uuid.uuid4()),
    timestamp=int(time.time()),
)

proof = client.disclosure_requests.get_proof(request["requestId"])
verified = client.disclosure_requests.verify_proof(proof["proof"]["proofToken"])
```

Supported methods:

- `client.disclosure_requests.list(...)`
- `client.disclosure_requests.create(...)`
- `client.disclosure_requests.get(request_id)`
- `client.disclosure_requests.get_proof(request_id)`
- `client.disclosure_requests.verify_proof(proof_token)`
- `client.disclosure_requests.list_templates()`
- `client.disclosure_requests.create_template(...)`
- `client.disclosure_requests.delete_template(template_id)`

## Compliance, AML, And Approvals

```python
overview = client.compliance.overview()
packet = client.compliance.packet("req_123")

aml = client.aml.create_smile_check(
    {"customerId": "cust_123", "fullName": "Ada Okafor", "countries": ["NG"]}
)

approvals = client.enterprise_approvals.list(status="pending")
```

Supported resources:

- `client.compliance.overview()`, `case(request_id)`, `packet(request_id)`
- `client.aml.create_smile_check(...)`, `get_smile_check(check_id)`, `create_smile_news(...)`, `get_smile_news(news_id)`, `risk_score(...)`, `transaction_monitoring(...)`
- `client.ongoing.enable(...)`, `disable(...)`, `status(customer_id)`, `changes(customer_id)`, `due_reviews(...)`
- `client.enterprise_approvals.list(...)`, `approve(...)`, `reject(...)`, `cancel(...)`
- `client.diagnostics.list(...)`, `retry(request_id, ...)`, `cancel(request_id, ...)`
- `client.api_settings.get()`, `update(...)`
- `client.api_keys.list(...)`, `create(...)`, `revoke(...)`, `validate_current()`

Use the generic paginator for cursor-based list endpoints:

```python
for item in client.paginate("/diagnostics/requests", limit=100):
    print(item)
```

## Webhooks

Register a webhook:

Webhook write calls generate a nonce and timestamp automatically. You can pass your own values when your infrastructure needs to correlate or pre-sign a request.

```python
import time
import uuid

webhook = client.webhooks.register(
    "https://example.com/webhooks/ontiver",
    ["verification.completed", "proof.issued"],
    nonce=str(uuid.uuid4()),
    timestamp=int(time.time()),
)

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

Webhook delivery retries are available through:

```python
retries = client.webhooks.retries()
deliveries = client.webhooks.deliveries(webhook_id="wh_123", status="failed")
```

Verify webhook signatures using the raw request body, then parse a typed payload:

```python
from ontiver.webhooks import parse_webhook_payload, verify_webhook_signature

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

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