huudis 0.4.0

Official Python SDK for Huudis — email/social/MFA, fine-grained authorization, webhook signature verification, and full admin API (IAM, workspaces, end-users, billing, webhook subscriptions) with OIDC device-flow auth and multi-profile session store.

huudis (Python)

Official Python SDK for Huudis. Works with FastAPI, Flask, Django, or anything else that speaks WSGI/ASGI.

Install

pip install huudis

Quickstart

Set env vars (or pass them to the client):

HUUDIS_ISSUER=https://huudis.com
HUUDIS_AUDIENCE=oc_your_client_id
HUUDIS_CLIENT_ID=oc_your_client_id
HUUDIS_CLIENT_SECRET=cs_...   # omit for public clients (PKCE)

Verify an access token

from fastapi import FastAPI, Header, HTTPException
from huudis import verify_access_token, HuudisAuthError

app = FastAPI()

@app.get("/me")
def me(authorization: str = Header(...)):
    try:
        claims = verify_access_token(authorization)
    except HuudisAuthError as e:
        raise HTTPException(401, detail=e.message)
    return {"user_id": claims.sub, "email": claims.email}

OIDC sign-in flow

from huudis import HuudisClient

huudis = HuudisClient()

# Step 1: redirect the user
url = huudis.authorization_url(
    redirect_uri="https://yourapp.com/callback",
    state=session["state"],
    code_challenge=session["pkce_challenge"],
)

# Step 2: exchange the code
tokens = huudis.exchange_code(
    code=request.args["code"],
    redirect_uri="https://yourapp.com/callback",
    code_verifier=session["pkce_verifier"],
)
userinfo = huudis.userinfo(tokens["access_token"])

Authorization check

result = huudis.authz_check(
    access_token=token,
    principal={"type": "user", "id": claims.sub, "accountId": claims.account_id},
    action="plugipay:DeleteInvoice",
    resource="forjio:plugipay::acc_.../invoice/inv_9F8",
)
if not result["allow"]:
    raise HTTPException(403, detail=result.get("reason"))

Types

Name	Description
verify_access_token(header_or_token, *, issuer=None, audience=None, require_mfa=False)	Module-level convenience — reads HUUDIS_ISSUER / HUUDIS_AUDIENCE from env.
HuudisClient(issuer=..., client_id=..., client_secret=..., audience=..., api_base=...)	Full surface. Use as a context manager (with HuudisClient() as huudis:) or call .close().
HuudisClaims	Dataclass returned by verification — sub, email, account_id, scope, mfa_verified, etc.
HuudisAuthError	Raised on any failure; carries .code + .message.

JWKS is cached in-process via PyJWT's PyJWKClient.

Docs

• Full docs: https://huudis.com/docs
• Source: https://github.com/hachimi-cat/saas-huudis/tree/master/sdk/python

License

MIT