zanii-id

Python SDK for Zanii ID — OAuth 2.1 / OpenID Connect sign-in for products in the Zanii ecosystem.

Authorization Code flow with mandatory PKCE, offline ID-token verification against the issuer's JWKS, and a FastAPI integration that mounts the whole login round-trip for you.

pip install zanii-id

Use it

Configuration comes from ZANII_ISSUER, ZANII_CLIENT_ID, ZANII_CLIENT_SECRET and ZANII_REDIRECT_URI, and is validated eagerly so a misconfigured deployment fails at startup rather than on a user's first login.

from zanii_id import ZaniiClient

zanii = ZaniiClient()
req = zanii.get_authorization_url()       # keep req.state / req.nonce / req.verifier in session
# ... redirect the user to req.url, then on your callback route:
tokens = await zanii.exchange_code(code, req, received_state)
claims = zanii.verify_id_token(tokens.id_token, nonce=req.nonce)
user = await zanii.get_user(tokens.access_token)

FastAPI

from zanii_id import ZaniiClient
from zanii_id.integrations.fastapi import build_auth_router, install_zanii, require_zanii_auth

zanii = ZaniiClient()
install_zanii(app, zanii, session_secret=SECRET)
app.include_router(build_auth_router(zanii, session_secret=SECRET))

@app.get("/dashboard")
async def dashboard(user = Depends(require_zanii_auth)):
    return {"zanii_user_id": user.zanii_user_id}

That mounts /auth/login, /auth/callback and /auth/logout. require_zanii_auth refreshes a stale access token once and rotates the session cookie before giving up.

Provisioning users locally

sub is an immutable zanii_user_id. Upsert on it — never on email, which users change:

INSERT INTO users (zanii_user_id, ...) VALUES ($1, ...)
ON CONFLICT (zanii_user_id) DO NOTHING;

Agent activity

If your product records agent receipts on the Zanii ledger, stamp them with the user's subject tag so they can audit their own slice:

from zanii_id.activity import subject_tag, fetch_activity   # pip install 'zanii-id[subject]'

tag = subject_tag(user.did, client_id)     # pass to record(..., subject_tag=tag)
entries = await fetch_activity(tag)        # every receipt verified offline

Invalid receipts come back with verified=False and a flag_reason rather than being dropped — a truncated slice appends its own flagged entry, so a cut page never reads as complete.

Lifecycle webhooks

Register a lifecycle_webhook_url on your client (console or /orgs/clients) and Zanii ID POSTs account events to it, signed over the raw body with the same webhook_secret you already hold: X-Zanii-Signature: sha256=<hmac> plus X-Zanii-Event. verify_lifecycle_event checks it in constant time and returns the parsed event. Give it the raw request bytes.

from zanii_id import LifecycleSignatureError, verify_lifecycle_event

@app.post("/webhooks/zanii-id")
async def lifecycle(request: Request):
    try:
        ev = verify_lifecycle_event(await request.body(), request.headers.get("X-Zanii-Signature"), WEBHOOK_SECRET)
    except LifecycleSignatureError:
        return Response(status_code=401)
    if ev.event == "user.deleted":
        await users.erase(ev.sub)
    return Response(status_code=204)

Deliveries retry with backoff for about an hour (8 attempts). Answer 2xx quickly and do the work afterwards. sub is the identifier you receive at login, so key on it as usual.

Two-step verification and amr

Every id_token carries amr: ["pwd", "otp"] when the user signed in with their authenticator, ["pwd"] otherwise. Tokens.id_claims["amr"] is where to look if a route needs step-up; send the user to {issuer}/ui/account to enrol.

Notes

• alg is pinned from the discovery document, never trusted from the token header.
• Token POSTs are never retried; grants are single-use.
• The JWKS cache refetches exactly once on an unseen kid, then fails hard.

Licence

Apache-2.0. See LICENSE.