Python SDK

Supports sync and async. Requires Python 3.9+.

Install

pip install authzx

Quick start

from authzx import AuthzX, Subject, Resource, Action

client = AuthzX(api_key="azx_...")

decision = client.check(
    subject=Subject(id="user-123", type="user"),
    action=Action(name="read"),
    resource=Resource(id="doc-456", type="document"),
)

Using with the local agent

client = AuthzX(base_url="http://localhost:8181")

Full response

from authzx import AuthorizeRequest

resp = client.authorize(AuthorizeRequest(
    subject=Subject(id="user-123", type="user", roles=["editor"]),
    resource=Resource(id="doc-456", type="document"),
    action=Action(name="read"),
    context={"ip": "10.0.0.1"},
))
# resp.decision, resp.context.reason, resp.context.policy_id, resp.context.access_path

Async

decision = await client.async_check(
    subject=Subject(id="user-123", type="user"),
    action=Action(name="read"),
    resource=Resource(id="doc-456", type="document"),
)

resp = await client.async_authorize(request)

FastAPI

from fastapi import FastAPI, Depends
from authzx import AuthzX

app = FastAPI()
authzx = AuthzX(api_key="azx_...")

@app.get("/documents/{id}")
async def get_doc(id: str, _=Depends(authzx.require("document", "read"))):
    return {"id": id}

Extracts subject ID from the X-User-ID header by default. Customize:

authzx.require("document", "read", subject_header="authorization-user-id")

Options

AuthzX(
    api_key="azx_...",
    base_url="http://localhost:8181",
    timeout=5.0,        # seconds, default 10
    max_retries=3,      # default 2
)

Error handling

from authzx import AuthzX, AuthzXError

try:
    client.check(subject, "read", resource)
except AuthzXError as e:
    if e.is_auth_error:
        # 401 — invalid API key
        pass
    if e.is_server_error:
        # 5xx — already retried
        pass
    print(e.status_code, e.message)

Client lifecycle

The Python SDK reuses HTTP connections. Close the client when done:

client = AuthzX(api_key="azx_...")
# ... use client ...
client.close()

# Or for async:
await client.async_close()

Types

Type	Fields
Subject	id, type (required), properties (alias: attributes), roles
Resource	id, type (required), properties (alias: attributes)
Action	name
AuthorizeRequest	subject, resource, action, context
AuthorizeResponse	decision, context
ResponseContext	reason, policy_id, access_path