zanii-connect — Python SDK

Python client for Zanii Connect: OAuth connections, encrypted token vault, and audited tool execution for AI agents.

Install

pip install zanii-connect

Requires Python 3.10+.

Quickstart

from zanii_connect import ZaniiClient

# Agents/services authenticate with a scoped API key:
nc = ZaniiClient(api_key="nsk_...")

# Or as a user (JWT):
nc = ZaniiClient(email="info@zanii.agency", password="...")

# Or with a bearer token you already hold — a vault session JWT, or a Zanii ID
# access token minted for the vault resource (aud = https://vault.zanii.agency/mcp):
nc = ZaniiClient(token="...")

print(nc.me()["organization"]["name"])

# Connect a provider (open the returned URL in a browser to complete OAuth):
url = nc.connect("gmail", redirect_url="https://vault.zanii.agency/api/v1/connect/oauth/callback")["url"]

# Discover tools and execute one:
conn = nc.connections()["connections"][0]
found = nc.execute("gmail.search", connection_id=conn["id"], parameters={"query": "invoice"})

# Actions that need human approval return an approval link instead of executing:
res = nc.execute("gmail.sendEmail", connection_id=conn["id"],
                 parameters={"to": "info@zanii.agency", "subject": "Hi", "body": "Hello"})
if res.get("requires_approval"):
    print("Ask a human to confirm:", res["approval_url"])

# Long-running work goes through the job queue:
job = nc.execute_async("browser.run", connection_id=conn["id"], parameters={...})
result = nc.wait_for_job(job["job_id"], timeout=300)

Async

from zanii_connect import AsyncZaniiClient

async with AsyncZaniiClient(api_key="nsk_...") as nc:
    tools = await nc.tools()

Same methods as the sync client; with email/password call await nc.login(email, password) once after construction.

Behavior

• Retries: 429/502/503/504 are retried up to 3 times with exponential backoff.
• Idempotency: pass idempotency_key= to execute() to make retries safe for side-effecting actions.
• Errors: non-2xx responses raise ZaniiError with .status_code and .detail. A failed tool call's .detail is the provider's real message (e.g. provider 404: Requested entity was not found.), never empty.
• MCP: AI agents that speak MCP don't need this SDK — point them at POST https://vault.zanii.agency/api/v1/mcp with an X-API-Key header.

Surface

Covers the full API:

• Account: signup, login, me, update_profile, change_password, forgot_password, reset_password, email verification, MFA (mfa_enroll/mfa_enable/mfa_disable)
• API keys: create_api_key (plaintext returned once), api_keys, delete_api_key
• Org & team: org, usage, update_org, export_org, delete_org, users, invite_user, update_user, deactivate_user, roles (permissions, roles, upsert_role, delete_role), workspaces/projects/environments
• Registry: providers, provider, provider_actions, actions, action, tools, tool, dynamic-registry admin (register_provider, register_action, unregister_action)
• Connections: connect, connections, connections_health, delete_connection, share_connection
• Execution: execute, execute_async, job, wait_for_job · approvals (approvals, approve)
• Browser sandbox: create_browser_session, browser_session, browser_run, browser_run_async
• Secrets / automation: secrets, set_secret, delete_secret, triggers, webhook subscriptions
• Observability: executions (each row carries receipt_hash + proof_url), audit, audit_export_csv, health
• Proof-of-action: receipts_bundle (offline-verifiable audit bundle), compliance_report (json/markdown)

License

MIT © Zanii Agency