Scoped Permissions: Overview
auth_middleware.authz answers “may this principal do X in this scope?”. It is
additive: require_groups, require_roles, require_permissions and the legacy
providers keep working untouched (they are “flat RBAC”).
Flat RBAC or scoped permissions?
Use
require_groups/require_roleswhen a token claim alone decides (anadminsgroup may call/admin).Use scoped permissions when the answer depends on where: the same person is an editor of one tenant, a reader of another and a stranger to the rest, and that membership lives in your database or in DynamoDB, not in the token.
Concepts
- Principal
The token
subplus optional tokengroups.- Scope
ScopeRef(kind, id), e.g.("studio", "<uuid>");ScopeRef.GLOBALis platform-wide.- Assignment
(principal, scope, role, status, revision). One active assignment per principal and scope.revisionstarts at 0 and grows by exactly 1 on every write (optimistic concurrency).- Role and catalog
A role is a name. The catalog maps
role -> permissions. The model is additive: nothing denies.- Decision
allowed,not_visibleordenied.
Two failure modes, on purpose
not visible (HTTP 404 by default): the principal has no active assignment in the scope, or the scope does not exist. Callers cannot tell the two apart, so tenants are not enumerable.
denied (HTTP 403 naming the permission): the principal has an assignment but lacks the permission.
A scope kind declared with hide_existence=False answers denied instead (used for the platform
scope, where there is nothing to hide).
Request flow
Request -> JwtAuthMiddleware -> request.state.current_user
|
+-> Depends(require_permission("design.write", scope=ScopeFromPath(...)))
|-> Authz (app.state.authz)
| |-> PermissionCatalog role -> permissions
| |-> store_factory(request) -> AssignmentStore (memory | SQL | DynamoDB | yours)
| |-> role resolvers [stored assignment, token groups -> role]
| `-> ErrorPolicy 404 / 403 / 401
`-> AuthzContext returned to the handler
The guard never skips when AUTH_MIDDLEWARE_DISABLED is set, and Authz.install refuses to
start in that state unless allow_disabled_for_development=True.
Next: The Permission Catalog, Assignment Stores, FastAPI Integration, Operations: Service, CLI, Cache, Audit, Migrating from Flat Permissions.