Metadata-Version: 2.4
Name: intflow-auth-admin-sdk
Version: 0.2.0
Summary: Server-only Intflow Auth Admin API SDK.
Author: Intflow
License: Proprietary
Requires-Python: >=3.12
Requires-Dist: httpx<1,>=0.28
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: hatchling<2,>=1.27; extra == 'dev'
Requires-Dist: mypy<2,>=1.13; extra == 'dev'
Requires-Dist: pytest-asyncio<2,>=1.3; extra == 'dev'
Requires-Dist: pytest-cov<8,>=6; extra == 'dev'
Requires-Dist: pytest<9,>=8; extra == 'dev'
Requires-Dist: ruff<1,>=0.9; extra == 'dev'
Requires-Dist: twine<7,>=6; extra == 'dev'
Description-Content-Type: text/markdown

# Intflow Auth Admin SDK

Server-only Python SDK for trusted backends that call the Intflow Auth Admin
API.

This package is for backend automation and integrated management services that
already have an operator Admin API token from their own secure runtime
configuration. It does not store local operator credentials, does not perform
browser login handoff, and must not be used from browser code.

`base_url` must be an origin-only HTTPS URL. Plain HTTP is accepted only for
exact `localhost`, `127.0.0.1`, or `::1` development origins. Userinfo, query,
fragment, path-prefix, ambiguous port/host forms, and redirects are rejected
before the SDK can forward an operator token.

## Install

```powershell
python -m pip install intflow-auth-admin-sdk
```

## Current Status

Use a trusted runtime secret source to supply the operator Admin API token.
Public request and response mappings are exported as `TypedDict` models, list
filters and factory options have explicit signatures, and misspelled options
are rejected by static type checkers. Audit event `payload` is the one
intentionally extensible JSON field and contains redacted metadata only.

```python
from intflow_auth_admin_sdk import create_admin_client

with create_admin_client(token="operator-admin-token") as client:
    actor = client.whoami()
    audit_events = client.search_audit_events(
        client_id="<oauth-client-id>",
        limit=25,
    )

print(actor["user"]["email"])
print(audit_events["next_cursor"])
```

### Errors And Retries

HTTP failures raise `IntflowAuthAdminHttpError`. Use its bounded metadata for
control flow instead of parsing exception text or raw upstream responses:

```python
from intflow_auth_admin_sdk import IntflowAuthAdminHttpError

try:
    client.whoami()
except IntflowAuthAdminHttpError as error:
    print(error.status_code, error.service_error_code or "http_error")
    if error.status_code == 429 and error.retry_after_seconds is not None:
        # Schedule a caller-controlled retry after this bounded delay.
        retry_delay = error.retry_after_seconds
    raise
```

`response_body` is size-bounded and recursively redacts sensitive fields and
known bearer values, but it remains untrusted upstream data and should not be
logged wholesale. Timeout and transport errors use stable SDK error codes and
do not retain a raw secret-bearing transport cause. The async client exposes
the same error contract.

Role grant/revoke, user session/refresh-token revoke-all, and app-admin revoke
return `None` only after an exact empty `204 No Content` response. They do not
return a user, count, or empty mapping.

Create only a finite child operator token from this bearer-authenticated SDK:

```python
created = client.create_operator_admin_token(
    {
        "name": "integrated-console-backend",
        "scopes": ["admin:audit:read"],
        "ttl_seconds": 3600,
    }
)
```

Operator-token response mappings include `parent_token_id`,
`lineage_root_token_id`, and `delegation_depth`. Revoking a token also revokes
its active descendants.

Requested scopes must be a non-empty subset of the SDK credential scopes, and
the child expiry cannot exceed the SDK credential expiry. No-expiry root
credentials require the separate privileged browser-session control path and
are rejected locally by this SDK.

Long-running trusted backends should create one `IntflowAuthAdminClient` or
`AsyncIntflowAuthAdminClient` during startup, reuse it for Admin API calls, and
call `close()` or `aclose()` during shutdown. Caller-injected `httpx` clients
remain caller-owned.

For mocked Admin API examples, see `examples/python-sdk-consumer`.
