litestar-permissions¶
Fine-grained hierarchical RBAC for Litestar applications.
Roles are scoped to resources (an org, a project, an app) and permissions inherit upward through the hierarchy. A user with org-admin on Organization X automatically has those permissions on every project and application inside it.
Built on SQLAlchemy 2.x. Ships as a Litestar plugin with guards, middleware, and dynamic model generation.
Installation¶
uv add litestar-permissions
pip install litestar-permissions
Quick Start¶
from litestar import Litestar, get
from litestar_permissions import PermissionsPlugin, PermissionsConfig, require_permission
from sqlalchemy.orm import DeclarativeBase
class Base(DeclarativeBase):
pass
config = PermissionsConfig(
hierarchy={"application": "project", "project": "organization"},
)
@get(
"/apps/{app_id:str}/deploy",
guards=[require_permission("application:deploy", resource_id_param="app_id")],
)
async def deploy(app_id: str) -> dict:
return {"status": "deploying"}
app = Litestar(
route_handlers=[deploy],
plugins=[PermissionsPlugin(config=config, base=Base)],
)
The plugin generates four SQLAlchemy tables (roles, permissions, role_permissions, user_role_assignments) bound to your Base. The resolver handles permission checks with an LRU cache and hierarchy traversal.
Set up the plugin, define your hierarchy, and run your first permission check.
How resource hierarchies work and how permissions inherit between levels.
Protect route handlers with require_permission and require_role guards.
Full API docs for all public classes, functions, and protocols.