bot/skills/hanzo-iam/SKILL.md

name, description, metadata

name	description	metadata
hanzo-iam	Authenticate users and manage identity with Hanzo IAM. OAuth2 flows, user CRUD, org management, JWT validation, and FastAPI integration via the hanzo-iam Python SDK.	bot requires install bins python3 id kind package label pip pip hanzo-iam Install Hanzo IAM SDK (pip)

Hanzo IAM — Identity & Access Management

pip install hanzo-iam

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)

Environment Variables

HANZO_IAM_ENDPOINT=https://iam.hanzo.ai   # IAM server URL
HANZO_IAM_CLIENT_ID=...                     # OAuth client ID
HANZO_IAM_CLIENT_SECRET=...                 # OAuth client secret
HANZO_IAM_ORG_NAME=HANZO                    # Organization name
HANZO_IAM_APP_NAME=your-app                 # Application name (optional)
HANZO_IAM_CERTIFICATE=path/to/cert.pem      # TLS cert (optional)

Supported Organizations

Org	Endpoint	Domain
HANZO	https://iam.hanzo.ai	hanzo.id
ZOO	https://iam.zoo.dev	zoo.id
LUX	https://iam.lux.network	lux.id
PARS	https://iam.pars.dev	pars.id

OAuth2 Authorization Code Flow

# Step 1: Get authorization URL (redirect user here)
auth_url = client.get_auth_url(
    redirect_uri="https://yourapp.com/callback",
    state="random-state-string",
    scope="openid profile email"
)

# Step 2: Exchange code for tokens (after callback)
tokens = client.get_token(code="auth-code-from-callback")
# tokens.access_token, tokens.refresh_token, tokens.expires_in

# Step 3: Get user info
user = client.get_user_info(access_token=tokens.access_token)
# user.id, user.name, user.email, user.avatar, user.owner (org)

Client Credentials Flow (Service-to-Service)

tokens = client.get_client_credentials_token()
# Use tokens.access_token for API calls between services

Refresh Token

new_tokens = client.refresh_token(refresh_token=tokens.refresh_token)

User Management

# List users
users = client.get_users()

# Get user by ID
user = client.get_user(user_id="user-123")

# Create user
user = client.create_user(
    name="Jane Doe",
    email="[email protected]",
    password="secure-password"
)

# Update user
client.update_user(user_id="user-123", name="Jane Smith")

# Delete user
client.delete_user(user_id="user-123")

Organization Management

orgs = client.get_organizations()
org = client.get_organization(name="HANZO")

JWT Validation

claims = client.parse_jwt(token=access_token)
# claims["sub"], claims["iss"], claims["exp"], etc.

FastAPI Integration

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

app = FastAPI()
auth = IAMAuth(config)

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

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

Async Client

from hanzo_iam import AsyncIAMClient

async_client = AsyncIAMClient(config)
user = await async_client.get_user_info(access_token=token)