ontiver 0.1.6

Official Python SDK for the Ontiver API

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:

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

After publication:

python -m pip install ontiver

Configuration

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

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:

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

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:

ontiver-smoke

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

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:

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:

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

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

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

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

import time
import uuid

request = client.disclosure_requests.create(
    user_email="[e-mail]",
    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

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:

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.

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:

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:

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:

X-Ontiver-Signature: sha256=<hex_digest>

Raw Request Escape Hatch

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

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

Errors

Catch specific exceptions:

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:

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:

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

Install from TestPyPI in a clean environment:

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:

python -m twine upload dist/*

Target package name: ontiver.