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.