fastapi-rbac-kit 0.1.0

Drop-in role-based access control for FastAPI — roles, permissions, decorators.

fastapi-rbac

Drop-in role-based access control for FastAPI. Define roles and permissions, protect endpoints with dependency injection.

Installation

pip install fastapi-rbac

Quick Start

from fastapi import FastAPI, Depends
from fastapi_rbac import RBAC, Permission, require_role, require_permission

app = FastAPI()
rbac = RBAC()  # comes with admin, editor, viewer roles

# Add a custom role
rbac.add_role("moderator", ["read", "write", "delete"])

Protecting Endpoints

By Role

Restrict access to specific roles:

from fastapi_rbac import require_role, set_default_rbac

set_default_rbac(rbac)

# Your auth dependency that returns a user object with a .role attribute
def get_current_user():
    ...

@app.get(
    "/admin/dashboard",
    dependencies=[require_role("admin", get_user=get_current_user)],
)
def admin_dashboard():
    return {"message": "Welcome, admin!"}


@app.get(
    "/content",
    dependencies=[require_role("admin", "editor", get_user=get_current_user)],
)
def manage_content():
    return {"message": "Content management"}

By Permission

Check if the user's role has a specific permission:

from fastapi_rbac import require_permission

@app.get(
    "/articles",
    dependencies=[require_permission("read", rbac=rbac, get_user=get_current_user)],
)
def list_articles():
    return {"articles": []}


@app.post(
    "/articles",
    dependencies=[require_permission("write", rbac=rbac, get_user=get_current_user)],
)
def create_article():
    return {"created": True}


@app.delete(
    "/articles/{id}",
    dependencies=[require_permission("delete", rbac=rbac, get_user=get_current_user)],
)
def delete_article(id: int):
    return {"deleted": id}

Built-in Roles

Role	Permissions
admin	All (wildcard)
editor	read, write
viewer	read

User Object Contract

Your authentication dependency must return an object with a .role attribute:

from dataclasses import dataclass

@dataclass
class User:
    id: int
    username: str
    role: str  # must match a registered role name

Custom Roles

rbac = RBAC()

# Add roles
rbac.add_role("moderator", ["read", "write", "delete"])
rbac.add_role("analyst", ["read", "export"])

# Check programmatically
rbac.check_permission("moderator", "delete")  # True
rbac.check_permission("analyst", "write")      # False

# List roles
rbac.roles  # ['admin', 'editor', 'viewer', 'moderator', 'analyst']

# Remove a role
rbac.remove_role("analyst")

Using request.state.user

If you prefer middleware-based auth, require_role and require_permission can read the user from request.state.user automatically when no get_user dependency is provided:

@app.middleware("http")
async def auth_middleware(request, call_next):
    request.state.user = authenticate(request)
    return await call_next(request)

# No get_user needed — reads from request.state.user
@app.get("/protected", dependencies=[require_role("admin")])
def protected():
    return {"ok": True}

Permission Constants

Use the Permission class for cleaner code:

from fastapi_rbac import Permission

rbac.add_role("support", [Permission.READ, Permission.WRITE])
rbac.check_permission("support", Permission.DELETE)  # False

License

MIT License. See LICENSE for details.