FastAPI Integration

Wiring

app = FastAPI(on_startup=[seed])
app.add_middleware(DemoAuth)
Authz.build(
    catalog=catalog,
    store=store,
    group_roles={"platform-admins": "PLATFORM_ADMIN"},  # token group -> global role
).install(app)


Authz.build validates the combination of sources (exactly one of store / store_factory, or only group_roles for a pure group setup). install stores the instance in app.state.authz, validates every guarded route against the catalog at startup (an unknown permission or a scope-kind mismatch fails the application start, not a request) and closes owned resources on shutdown.

Guarding routes

@app.get(
    "/studios/{studio_id}/design",
    openapi_extra=permission_extra("design.read"),
)
async def read_design(
    studio_id: str,
    ctx: AuthzContext = Depends(require_permission("design.read", scope=studio)),
) -> dict[str, object]:
    return {"studio": studio_id, "roles": sorted(ctx.roles)}


require_permission(permission, scope=..., authz=...) returns an AuthzContext (principal, scope, roles, permissions, attributes) and also stores it in request.state.authz_context. Scope sources: GlobalScope(), ScopeFromPath(kind, param), ScopeFromCallable(kind, fn). For non-raising checks inside a handler use await has_permission(request, permission, scope).

No authenticated user, or the placeholder synthetic user the middleware creates when authentication is disabled, gets 401 with WWW-Authenticate: Bearer.

Error policy

ErrorPolicy decides which exception each outcome raises. Defaults: not visible 404; denied 403 with {"detail": {"error": "forbidden", "required_permission": "..."}}; unauthenticated 401. Pass your own callables to Authz.build(error_policy=ErrorPolicy(denied=...)) to change status codes or bodies.

OpenAPI and architecture tests

openapi_extra=permission_extra("design.write") publishes x-permission; declared_permissions(app) returns {(METHOD, path): permission | None} for every operation, so an architecture test can assert that no route is unguarded.

Mounted sub-applications

A mounted app has its own app.state. Either call install on each app that uses the guard, or pass authz= explicitly to require_permission.