Python SDK

The beta guardhouse package provides Client Credentials, generic authenticated HTTP calls, JWT or introspection token validation, and FastAPI/Flask helpers.

Install

pip install guardhouse "pydantic>=2"

For framework helpers:

pip install guardhouse[fastapi]
# or
pip install guardhouse[flask] "pydantic>=2"

Beta packaging

The current beta uses Pydantic 2 at runtime. Install it explicitly unless another selected extra already provides it.

Python 3.9 and later are supported. Keep client and introspection secrets in a server-side secret store.

Request A Machine Token

from guardhouse import GuardhouseClient

async def get_token() -> str:
    async with GuardhouseClient(
        authority="https://your-tenant.guardhouse.cloud",
        client_id="YOUR_CLIENT_ID",
        client_secret="YOUR_CLIENT_SECRET",
        scope="orders.read",
    ) as client:
        return await client.get_access_token_async()

The client caches access tokens in memory and reacquires them before expiry.

Prefer async client APIs

Use the asynchronous token and HTTP methods in this beta. The token verifier's synchronous API remains available for synchronous request-validation paths.

Call The System API

Configure the client with scope="system_api", then use the generic async HTTP methods:

async def get_users(client):
    response = await client.get_async(
        "https://your-tenant.guardhouse.cloud/api/v1/users",
        params={"pageSize": 20, "offset": 0},
    )
    response.raise_for_status()
    return response.json()

The Python SDK has no typed System API models. Follow the endpoint reference for current routes, request bodies, and responses.

Protect A FastAPI Application

Introspection avoids distributing signing-key assumptions and checks token activity with Guardhouse:

from fastapi import Depends, FastAPI
from guardhouse.middleware import User, requires_auth

app = FastAPI()
get_caller = requires_auth(
    authority="https://your-tenant.guardhouse.cloud",
    audience="orders_api",
    validation_mode="introspection",
    introspection_client_id="YOUR_RESOURCE_CLIENT_ID",
    introspection_client_secret="YOUR_RESOURCE_CLIENT_SECRET",
)

@app.get("/orders")
async def orders(caller: User = Depends(get_caller)):
    return {"subject": caller.sub, "orders": []}

The Flask equivalent is FlaskAuthExtension, with @auth.requires_auth and an optional required scope.

Local JWT Validation

TokenVerifier also supports validation_mode="jwt_signature", issuer, audience, lifetime, and RS256 validation.

Beta JWT compatibility

Local JWT validation in this beta requires a tenant-compatible JWKS endpoint. Confirm it works in your environment before choosing JWT mode; otherwise use introspection.

Main APIs

API	Purpose
GuardhouseClient.get_access_token_async()	Acquire or reuse a machine token
request_async() and HTTP verb helpers	Make authenticated HTTP requests
introspect_token_async()	Read the RFC 7662-style active-token response
TokenVerifier.verify() / verify_async()	Validate and return token claims
TokenVerifier.has_scope()	Check a space-delimited or list scope claim
requires_auth()	Create a FastAPI authentication dependency
FlaskAuthExtension	Add Flask authentication decorators

Errors And Current Boundaries

The public exceptions include GuardhouseAuthError, GuardhouseNetworkError, TokenValidationError, TokenExpiredError, InvalidAlgorithmError, and JWKSFetchError.

• The package is beta; pin a tested version and review release notes before upgrading.
• The SDK exposes generic HTTP methods but no typed user, role, or permission client.
• Token and introspection caches are process-local.
• Keep M2M and introspection credentials out of client applications.

See Errors and limits for server status codes and retry guidance.