Python SDK

wocha is the Python SDK for the Wocha authentication and authorisation platform Management API. Use it for server-side user management, permissions, webhooks, and tenant configuration.

Installation

pip install wocha

Requires Python 3.10+.

Configuration

Use tenant for Wocha Cloud — the SDK resolves https://{tenant}.api.wocha.ai/v1:

from wocha import WochaClient
 
client = WochaClient(
    tenant="acme",
    api_key="wocha_mgmt_...",
)

For self-hosted deployments, pass base_url instead:

client = WochaClient(
    base_url="https://your-domain.com/v1",
    api_key="...",
)

Environment variables WOCHA_API_KEY and WOCHA_TENANT are used as fallbacks.

Quick start

users = client.users.list(page_size=25)
for user in users["data"]:
    print(user["email"])

Async client

from wocha import AsyncWochaClient
 
async with AsyncWochaClient(tenant="acme", api_key="...") as client:
    users = await client.users.list(page_size=25)
    allowed = await client.permissions.check(
        user_id="user-456",
        permission="edit",
        resource_type="document",
        resource_id="doc-123",
    )

Key resources

Resource	Example
`users`	`client.users.create(email="alice@example.com")`; `send_recovery(id, send=False)`
`organisations`	`client.organisations.create(...)`; `invite(org_id, email="…", send=False)`
`permissions`	`client.permissions.check(...)`
`sessions`	`client.sessions.revoke_all("usr_abc")`
`webhooks`	Verify with `wocha.webhooks.verify_webhook()`
`applications`	`client.applications.rotate_secret("app_abc")`

Organisation invites

invite = client.organisations.invite(
    "org_abc",
    email="alex@example.com",
    role="member",
    return_to="https://app.example.com/api/auth/login",
    send=False,
)
print(invite["action_url"])

See Organisation invites.

Error handling

from wocha import NotFoundError, RateLimitError, AuthenticationError
 
try:
    user = client.users.get("nonexistent")
except NotFoundError as e:
    print(e.error_code, e.request_id)
except RateLimitError as e:
    print(e.retry_after)