depends

FastAPI dependencies for authentication and authorization.

Classes:

• FastAPIPermissions –

  FastAPI-aware permission checker that extends :class:Permissions.

• FastAPIRoles –

  FastAPI role checker that requires no configuration.

Functions:

• get_current_user –

  Extract the authenticated user from request state (set by AuthMiddleware).

• require_permission –

  Return a FastAPI dependency that enforces the given permission.

• require_roles –

  Return a FastAPI dependency that raises 403 if the user holds none of the roles.

FastAPIPermissions

FastAPIPermissions(
    role_permissions: dict[str, frozenset[str]],
)

              flowchart TD
              oqtopus_auth.fastapi.depends.FastAPIPermissions[FastAPIPermissions]
              oqtopus_auth.permissions.Permissions[Permissions]

                              oqtopus_auth.permissions.Permissions --> oqtopus_auth.fastapi.depends.FastAPIPermissions
                


              click oqtopus_auth.fastapi.depends.FastAPIPermissions href "" "oqtopus_auth.fastapi.depends.FastAPIPermissions"
              click oqtopus_auth.permissions.Permissions href "" "oqtopus_auth.permissions.Permissions"
            

FastAPI-aware permission checker that extends :class:Permissions.

Adds :meth:require, a FastAPI dependency factory, to the framework-agnostic :meth:has_permission inherited from the base class.

Create one instance per application and use it as follows::

permissions = FastAPIPermissions(role_permissions)

@router.get("/settings", dependencies=[permissions.require("app_settings.get")])
async def settings(request: Request) -> HTMLResponse:
    can_edit = permissions.has_permission(
        request.state.user, "app_settings.update"
    )

Methods:

• has_permission –

  Return True if the user holds the given permission.

• require –

  Return a FastAPI dependency that raises 403 if the permission is absent.

has_permission

has_permission(
    user: AuthUser | None, permission: str
) -> bool

Return True if the user holds the given permission.

Returns:

• bool –

  True if the user has the permission, False otherwise.

require

require(permission: str) -> Depends

Return a FastAPI dependency that raises 403 if the permission is absent.

Returns:

• Depends –

  A Depends instance suitable for dependencies=[...].

FastAPIRoles

FastAPI role checker that requires no configuration.

Roles are read directly from the authenticated user set by AuthMiddleware. Use this when you need role-based access control without a permission mapping.

require() is a static method, so instantiation is not required. Prefer the standalone :func:require_roles function for route decorators::

@router.get("/admin", dependencies=[require_roles("admin")])
async def admin_page(request: Request) -> HTMLResponse:
    ...

# Multiple roles: pass if the user holds ANY of the specified roles
@router.get("/ops", dependencies=[require_roles("admin", "operator")])
async def ops_page(request: Request) -> HTMLResponse:
    ...

FastAPIRoles is retained for cases where a class interface is preferred for consistency with :class:FastAPIPermissions.

Methods:

• require –

  Return a dependency that raises 403 if the user holds none of the roles.

require staticmethod

require(*roles: str) -> Depends

Return a dependency that raises 403 if the user holds none of the roles.

Pass one or more role names. Access is granted when the user holds at least one of them (OR logic).

Returns:

• Depends –

  A Depends instance suitable for dependencies=[...].

get_current_user

get_current_user(request: Request) -> AuthUser | None

Extract the authenticated user from request state (set by AuthMiddleware).

Returns:

• AuthUser | None –

  The authenticated user, or None when no user is present.

Raises:

• RuntimeError –

  If AuthMiddleware was never registered on the app.

require_permission

require_permission(permission: str) -> Depends

Return a FastAPI dependency that enforces the given permission.

Reads the :class:FastAPIPermissions instance from request.app.state.permissions. This is a convenience function for applications where route modules are imported before the FastAPIPermissions instance is constructed (e.g. when routes are registered inside an application factory).

For new projects that control the import order, prefer FastAPIPermissions.require() instead.

Returns:

• Depends –

  A Depends instance that raises 403 if the check fails, or 500

• Depends –

  if no permissions are configured.

require_roles

require_roles(*roles: str) -> Depends

Return a FastAPI dependency that raises 403 if the user holds none of the roles.

Pass one or more role names. Access is granted when the user holds at least one of them (OR logic).

Reads roles directly from the authenticated user — no permission mapping needed. Use this when you want role-based access control without a permissions: config section.

Returns:

• Depends –

  A Depends instance that raises 403 if the check fails.