intflow-auth-admin-sdk 0.2.0

Server-only Intflow Auth Admin API SDK.

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

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.

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:

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:

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.