# Python SDK

Typed sync (`OhAuthCat`) and async (`AsyncOhAuthCat`) clients.

## Install

```sh
pip install ohauthcat
```

## Configure

`OhAuthCat(api_key="sk_...")` creates the client; for sign-in also pass `client_id="pk_..."` and `environment_id="env_..."`. Optional: `timeout_ms`, `max_retries`, and `api_base_url` / `auth_base_url` for any deployment other than production. Use it as a context manager (`with OhAuthCat(...) as client:`) so its HTTP client is closed.

## First call

Every API operation is a method on its resource: `client.organizations.create_organization(body=models.OrganizationCreate(name="Example"))`, or `client.organizations.get_organization(path={"org": "org_..."})`. `client.events.list()` iterates forwards over every event. On `AsyncOhAuthCat`, await the same methods.

SSO: `client.sso.get_authorization_url(redirect_uri=..., state=...)` returns `.url` and `.code_verifier`; store both in your server session. On the callback, compare the state, then call `client.sso.get_profile_and_token(code=..., code_verifier=..., redirect_uri=...)` once. The [Python quickstart](/get-started/quickstart-python/) shows the complete flow with state, session binding and replay checks.

## Errors

Every API error is an `OhAuthCatError` with the stable `code`, `status`, `type`, `param`, `doc_url` and `request_id`; see the [error codes](/errors/). `PlanLimitReachedError` adds the `metric` a plan refused. `RestartSignIn` means the code exchange cannot be retried: start a fresh sign-in.

## Webhooks

`webhooks.verify(raw_body, header, [secret])` (from `ohauthcat import webhooks`) checks the `OhAuthCat-Signature` header against the exact raw body bytes and returns the event. Pass every secret you hold during a rotation. A refusal raises `ohauthcat.webhooks.WebhookVerificationError` whose `code` is, for example, `signature_invalid` or `timestamp_outside`.

## Reference

Every method maps to an operation in the [API reference](/reference/api/); webhook payloads are in [webhook events](/reference/webhook-events/).
