> Markdown version of https://authpi.com/docs/sdks/admin-python/ — fetch the complete AuthPI docs index at https://authpi.com/llms.txt to discover all available pages.

# Admin SDK — Python

Manage AuthPI from Python backends with authpi-admin — async-first issuer, user, organization, and webhook management with typed models and auto-pagination.

[`authpi-admin`](https://pypi.org/project/authpi-admin/) is the official Python SDK for the AuthPI Core API — issuers, users, organizations, clients, webhooks, API keys, and events from your backend, with Pydantic-typed responses.

**Requirements:** Python 3.11+. The SDK is **async-only**, built on `httpx` — every call is awaited, and the client is an async context manager.

## Install

```bash
pip install authpi-admin
```

## Initialize

Authenticate with an [API key](/docs/guides/api-keys) — an id + secret pair passed as a tuple:

```python
from authpi_admin import AuthPIAdmin

async with AuthPIAdmin(api_key=("key_xxx", "your_key_secret")) as admin:
    page = await admin.issuers.list(limit=10)
```

`account_id` is optional: when omitted, the SDK resolves it once via `GET /v1/me` on the first request and caches it — an API key always maps to exactly one account. Pass it explicitly to skip that lookup.

For server-side calls on behalf of a user session, pass `access_token` instead, optionally with an `on_token_expired` async callback — the SDK invokes it on 401s and retries with the fresh token.

## Common tasks

**Manage users in an issuer.** Account-level resources hang off `admin` directly (`issuers`, `webhooks`, `events`, `api_keys`, `domains`, `credits`); per-issuer ones off `admin.issuer(id)`:

```python
user = await admin.issuer("i_4r8w2k9m5x1p7q3e6t0y2u4i8").users.create({
    "email": "alice@example.com",
    "display_name": "Alice",
})

users = await admin.issuer("i_4r8w2k9m5x1p7q3e6t0y2u4i8").users.list(limit=50)
```

**Paginate everything.** `list()` returns one page; `list_all()` is an async iterator that follows cursors for you:

```python
async for user in admin.issuer("i_4r8w2k9m5x1p7q3e6t0y2u4i8").users.list_all():
    print(user.id)
```

**Subscribe to events with a webhook:**

```python
webhook = await admin.webhooks.create({
    "url": "https://api.example.com/hooks/authpi",
    "auth": {"type": "bearer"},  # token generated and returned once in the response
    "events": ["user.created", "organization.suspended", "organization.deleted"],
})
```

## Error handling

Failures raise typed subclasses of `ApiError` — `AuthenticationError` (401), `ForbiddenError` (403), `NotFoundError` (404), `ValidationError` (400, with field details), `ConflictError`, `RateLimitError`, `ServerError`:

```python
from authpi_admin import NotFoundError, ValidationError

try:
    user = await admin.issuer(issuer_id).users.get(user_id)
except NotFoundError:
    user = None
except ValidationError as e:
    print(e.fields)
```

## Next steps

- [Issue and manage API keys](/docs/guides/api-keys) — creating the credential this SDK authenticates with
- [Organization lifecycle](/docs/guides/org-lifecycle) — the guarantees behind the org operations you'll call
- [Core API reference](/docs/reference/core-api/) — every endpoint the SDK wraps
- [Package on PyPI](https://pypi.org/project/authpi-admin/) — full README and advanced options