hanzoai-iam

Identity and Access Management SDK for the Hanzo ecosystem. Organization-aware multi-tenant IAM for the Hanzo ecosystem.

The PyPI distribution is hanzoai-iam; the import path is hanzo_iam.

Installation

pip install hanzoai-iam

With FastAPI integration:

pip install hanzoai-iam[fastapi]

With KMS support for certificate management:

pip install hanzoai-iam[kms]

Quick Start

from hanzo_iam import IAMClient, IAMConfig

config = IAMConfig(
    endpoint="https://iam.hanzo.ai",
    client_id="your-client-id",
    client_secret="your-client-secret",
    org_name="HANZO",
)

client = IAMClient(config)

# Get authorization URL for user login
auth_url = client.get_auth_url(redirect_uri="https://yourapp.com/callback")

# Exchange code for tokens
tokens = client.get_token(code="auth-code-from-callback")

# Get user info
user = client.get_user_info(access_token=tokens.access_token)

Organizations

Environment Variables

One canonical prefix — IAM_*. No upstream-brand aliases, no per-org variants.

# Required
IAM_ENDPOINT=https://hanzo.id
IAM_CLIENT_ID=your-client-id
IAM_CLIENT_SECRET=your-client-secret

# Optional (defaults shown)
IAM_ORG=hanzo
IAM_APP=app
IAM_CERT=path/to/cert.pem    # PEM file or inline PEM content

FastAPI Integration

from fastapi import FastAPI, Depends
from hanzo_iam.fastapi import IAMAuth, get_current_user
from hanzo_iam import IAMConfig, User

app = FastAPI()

config = IAMConfig.from_env()
auth = IAMAuth(config)

@app.get("/protected")
async def protected_route(user: User = Depends(auth.require_user)):
    return {"user": user.name, "org": user.owner}

@app.get("/optional")
async def optional_auth(user: User | None = Depends(auth.optional_user)):
    if user:
        return {"message": f"Hello, {user.name}"}
    return {"message": "Hello, anonymous"}

Client Credentials Flow

For service-to-service authentication:

from hanzo_iam import IAMClient, IAMConfig

config = IAMConfig(
    endpoint="https://iam.hanzo.ai",
    client_id="service-client-id",
    client_secret="service-client-secret",
    org_name="HANZO",
)

client = IAMClient(config)

# Get service token
tokens = client.get_client_credentials_token()

# Use token for API calls
headers = {"Authorization": f"Bearer {tokens.access_token}"}

Async Client

import asyncio
from hanzo_iam import AsyncIAMClient, IAMConfig

async def main():
    config = IAMConfig.from_env()
    client = AsyncIAMClient(config)

    # All methods are async
    tokens = await client.get_client_credentials_token()
    user = await client.get_user_info(tokens.access_token)

    print(f"Authenticated as: {user.name}")

asyncio.run(main())

API Reference

License

Apache-2.0