API Route RBAC Enforcement

Workspace membership enforcement on all API routes with require_workspace_member dependency

API Route RBAC Enforcement protects workspace-scoped resources by requiring valid membership before allowing access to any workspace endpoints.

Quick Start

1. Protected Route Access

   from praisonai_platform.client import PlatformClient
   
   # All workspace routes now require membership
   client = PlatformClient("http://localhost:8000", token="your-jwt-token")
   
   # This will only succeed if you're a member of the workspace
   projects = await client.list_projects("ws-abc123")
   
2. Membership Validation

   from praisonai_platform.api.deps import require_workspace_member
   from fastapi import Depends
   
   # FastAPI route with RBAC enforcement
   @router.get("/{workspace_id}/projects/")
   async def list_projects(
       workspace_id: str,
       user: AuthIdentity = Depends(require_workspace_member),  # ← RBAC enforcement
       session: AsyncSession = Depends(get_db),
   ):
       # User is guaranteed to be a workspace member here
       project_service = ProjectService(session)
       return await project_service.list_for_workspace(workspace_id)
   
3. Role-based Access Control

   from praisonai_platform.api.deps import require_workspace_member
   from functools import partial
   
   # Require admin role or higher
   require_admin = partial(require_workspace_member, min_role="admin")
   
   @router.delete("/{workspace_id}/projects/{project_id}")
   async def delete_project(
       workspace_id: str,
       project_id: str,
       user: AuthIdentity = Depends(require_admin),  # ← Admin required
       session: AsyncSession = Depends(get_db),
   ):
       # User has admin privileges in this workspace
       pass
   

---

How It Works

Component	Responsibility
require_workspace_member	FastAPI dependency that enforces workspace membership
MemberService.has_role()	Database query to verify user’s workspace membership and role
AuthIdentity	Enhanced with workspace_id for downstream route handlers
403 Forbidden	Returned to non-members attempting workspace access

---

Implementation Details

RBAC Dependency

The require_workspace_member dependency replaces get_current_user in all workspace-scoped routes:

# Before (GAP-8): Only authentication
@router.get("/{workspace_id}/projects/")
async def list_projects(
    workspace_id: str,
    user: AuthIdentity = Depends(get_current_user),  # ← Only checks valid token
    session: AsyncSession = Depends(get_db),
):
    pass

# After (GAP-8): Authentication + Authorization
@router.get("/{workspace_id}/projects/")
async def list_projects(
    workspace_id: str,
    user: AuthIdentity = Depends(require_workspace_member),  # ← Checks membership
    session: AsyncSession = Depends(get_db),
):
    # user.workspace_id is now available
    pass

Dependency Configuration

from praisonai_platform.api.deps import require_workspace_member
from functools import partial

# Default: requires "member" role or higher
require_member = require_workspace_member

# Custom: require "admin" role or higher
require_admin = partial(require_workspace_member, min_role="admin")

# Custom: require "owner" role
require_owner = partial(require_workspace_member, min_role="owner")

Role Hierarchy

---

Protected Routes

All workspace-scoped API routes now enforce membership:

Core Resources

Route Pattern	Enforcement	Minimum Role
GET /workspaces/{id}	✅	member
PATCH /workspaces/{id}	✅	admin
DELETE /workspaces/{id}	✅	owner
GET /workspaces/{id}/members	✅	member
POST /workspaces/{id}/members	✅	admin

Project Management

Route Pattern	Enforcement	Minimum Role
GET /workspaces/{id}/projects/	✅	member
POST /workspaces/{id}/projects/	✅	member
PATCH /workspaces/{id}/projects/{pid}	✅	member
DELETE /workspaces/{id}/projects/{pid}	✅	admin

Issue Tracking

Route Pattern	Enforcement	Minimum Role
GET /workspaces/{id}/issues/	✅	member
POST /workspaces/{id}/issues/	✅	member
GET /workspaces/{id}/issues/{iid}	✅	member
PATCH /workspaces/{id}/issues/{iid}	✅	member
DELETE /workspaces/{id}/issues/{iid}	✅	admin

Agent Management

Route Pattern	Enforcement	Minimum Role
GET /workspaces/{id}/agents/	✅	member
POST /workspaces/{id}/agents/	✅	member
PATCH /workspaces/{id}/agents/{aid}	✅	member
DELETE /workspaces/{id}/agents/{aid}	✅	admin

---

Error Responses

403 Forbidden - Non-Member

When a valid user attempts to access a workspace they’re not a member of:

{
  "detail": "User is not a member of this workspace",
  "status_code": 403
}

403 Forbidden - Insufficient Role

When a member lacks the required role level:

{
  "detail": "Insufficient permissions. Requires admin role or higher",
  "status_code": 403
}

401 Unauthorized

When authentication fails (invalid/missing token):

{
  "detail": "Invalid or expired token",
  "status_code": 401
}

---

API Testing

Valid Member Access

# Member accessing their workspace (✅ Success)
curl -H "Authorization: Bearer $MEMBER_TOKEN" \
  http://localhost:8000/api/v1/workspaces/ws-abc123/projects/

# Response: 200 OK with project list

Non-Member Access

# Non-member attempting access (❌ Forbidden)
curl -H "Authorization: Bearer $OTHER_USER_TOKEN" \
  http://localhost:8000/api/v1/workspaces/ws-abc123/projects/

# Response: 403 Forbidden

Role-based Access

# Member trying admin action (❌ Forbidden)
curl -X DELETE -H "Authorization: Bearer $MEMBER_TOKEN" \
  http://localhost:8000/api/v1/workspaces/ws-abc123/projects/proj-123

# Response: 403 Forbidden (requires admin)

# Admin performing same action (✅ Success)
curl -X DELETE -H "Authorization: Bearer $ADMIN_TOKEN" \
  http://localhost:8000/api/v1/workspaces/ws-abc123/projects/proj-123

# Response: 204 No Content

---

Migration Impact

Behavior Changes

Scenario	Before GAP-8	After GAP-8
Valid user, non-member	✅ Access granted	❌ 403 Forbidden
Valid user, workspace member	✅ Access granted	✅ Access granted
Invalid token	❌ 401 Unauthorized	❌ 401 Unauthorized

Client Impact

# SDK automatically handles the new authorization requirements
from praisonai_platform.client import PlatformClient

# This client request will now fail if user is not a workspace member
client = PlatformClient("http://localhost:8000", token="user-token")

try:
    projects = await client.list_projects("ws-abc123")
    print("Access granted - user is a member")
except Exception as e:
    print(f"Access denied: {e}")
    # Handle 403 Forbidden appropriately

---

Best Practices

Handle Authorization Errors Gracefully

Always handle 403 Forbidden responses in client applications. Display user-friendly messages when workspace access is denied rather than generic error messages.

Use Appropriate Role Requirements

Configure route dependencies with the minimum required role. Don’t require admin for operations that member can safely perform.

Validate Membership Before UI Actions

Check user workspace membership before displaying UI elements like “Create Project” buttons to prevent unsuccessful API calls.

Monitor Failed Authorization Attempts

Log and monitor 403 responses to identify potential security issues or UX problems with workspace access patterns.

---

Testing

Verify RBAC enforcement with the integration test suite:

# Run RBAC enforcement tests
pytest tests/test_new_api_integration.py::TestRBACEnforcement -v

# Run specific workspace access tests
pytest tests/test_new_api_integration.py -k "test_workspace_member" -v

Expected test scenarios:

• Non-member 403 responses on all workspace routes
• Member access granted for basic operations
• Admin role enforcement for management operations
• Owner role enforcement for destructive operations

---

Related

Team Members & RBAC

Learn about workspace member management

Authentication

Understand JWT token authentication