Enterprise RBAC API Reference

🔐 RBAC API Overview

The RecoAgent Enterprise RBAC API provides comprehensive role-based access control with fine-grained permissions, hierarchical roles, and audit logging for enterprise security.

🚀 Authentication

API Key Authentication

Authorization: Bearer sk-enterprise-123

RBAC Token Authentication

Authorization: Bearer <rbac_token>

📚 API Endpoints

1. Role Management

Create Role

POST /api/v2/rbac/roles

Request Body:

{
  "name": "analyst",
  "description": "Data analyst role with read access",
  "permissions": [
    "data:read",
    "analytics:read",
    "models:read"
  ],
  "inherits_from": ["viewer"],
  "tenant_id": "tenant_abc"
}

Response:

{
  "status": "success",
  "role": {
    "id": "role_123",
    "name": "analyst",
    "description": "Data analyst role with read access",
    "permissions": [
      "data:read",
      "analytics:read",
      "models:read"
    ],
    "inherits_from": ["viewer"],
    "tenant_id": "tenant_abc",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

Get Role

GET /api/v2/rbac/roles/{role_id}

Response:

{
  "status": "success",
  "role": {
    "id": "role_123",
    "name": "analyst",
    "description": "Data analyst role with read access",
    "permissions": [
      "data:read",
      "analytics:read",
      "models:read"
    ],
    "inherits_from": ["viewer"],
    "tenant_id": "tenant_abc",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

Update Role

PUT /api/v2/rbac/roles/{role_id}

Request Body:

{
  "description": "Updated analyst role with enhanced permissions",
  "permissions": [
    "data:read",
    "data:write",
    "analytics:read",
    "analytics:write",
    "models:read"
  ]
}

Response:

{
  "status": "success",
  "role": {
    "id": "role_123",
    "name": "analyst",
    "description": "Updated analyst role with enhanced permissions",
    "permissions": [
      "data:read",
      "data:write",
      "analytics:read",
      "analytics:write",
      "models:read"
    ],
    "inherits_from": ["viewer"],
    "tenant_id": "tenant_abc",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T12:00:00Z"
  }
}

Delete Role

DELETE /api/v2/rbac/roles/{role_id}

Response:

{
  "status": "success",
  "message": "Role deleted successfully"
}

2. Permission Management

Create Permission

POST /api/v2/rbac/permissions

Request Body:

{
  "name": "data:write",
  "description": "Write access to data resources",
  "resource": "data",
  "action": "write",
  "conditions": {
    "tenant_id": "tenant_abc"
  }
}

Response:

{
  "status": "success",
  "permission": {
    "id": "perm_123",
    "name": "data:write",
    "description": "Write access to data resources",
    "resource": "data",
    "action": "write",
    "conditions": {
      "tenant_id": "tenant_abc"
    },
    "created_at": "2024-01-01T00:00:00Z"
  }
}

List Permissions

GET /api/v2/rbac/permissions

Query Parameters:

• resource: Filter by resource type
• action: Filter by action type
• tenant_id: Filter by tenant

Response:

{
  "status": "success",
  "permissions": [
    {
      "id": "perm_123",
      "name": "data:write",
      "description": "Write access to data resources",
      "resource": "data",
      "action": "write",
      "conditions": {
        "tenant_id": "tenant_abc"
      }
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

3. User Role Assignment

Assign Role to User

POST /api/v2/rbac/users/{user_id}/roles

Request Body:

{
  "role_id": "role_123",
  "tenant_id": "tenant_abc",
  "assigned_by": "admin_user_123",
  "expires_at": "2024-12-31T23:59:59Z"
}

Response:

{
  "status": "success",
  "assignment": {
    "id": "assign_123",
    "user_id": "user_123",
    "role_id": "role_123",
    "tenant_id": "tenant_abc",
    "assigned_by": "admin_user_123",
    "expires_at": "2024-12-31T23:59:59Z",
    "created_at": "2024-01-01T00:00:00Z"
  }
}

Get User Roles

GET /api/v2/rbac/users/{user_id}/roles

Response:

{
  "status": "success",
  "roles": [
    {
      "id": "role_123",
      "name": "analyst",
      "description": "Data analyst role with read access",
      "permissions": [
        "data:read",
        "analytics:read",
        "models:read"
      ],
      "assigned_at": "2024-01-01T00:00:00Z",
      "expires_at": "2024-12-31T23:59:59Z"
    }
  ]
}

Remove Role from User

DELETE /api/v2/rbac/users/{user_id}/roles/{role_id}

Response:

{
  "status": "success",
  "message": "Role removed from user successfully"
}

4. Permission Checking

Check User Permission

POST /api/v2/rbac/check-permission

Request Body:

{
  "user_id": "user_123",
  "permission": "data:read",
  "resource_id": "data_456",
  "tenant_id": "tenant_abc"
}

Response:

{
  "status": "success",
  "has_permission": true,
  "permission_source": "role:analyst",
  "conditions_met": true
}

Get User Permissions

GET /api/v2/rbac/users/{user_id}/permissions

Query Parameters:

• tenant_id: Filter by tenant
• resource: Filter by resource type
• action: Filter by action type

Response:

{
  "status": "success",
  "permissions": [
    {
      "name": "data:read",
      "resource": "data",
      "action": "read",
      "source": "role:analyst",
      "conditions": {
        "tenant_id": "tenant_abc"
      }
    }
  ],
  "total": 1
}

5. Audit Logging

Get Audit Logs

GET /api/v2/rbac/audit-logs

Query Parameters:

• user_id: Filter by user
• action: Filter by action type
• resource: Filter by resource
• start_date: Start date filter
• end_date: End date filter
• page: Page number
• per_page: Items per page

Response:

{
  "status": "success",
  "audit_logs": [
    {
      "id": "audit_123",
      "user_id": "user_123",
      "action": "role_assigned",
      "resource": "role:analyst",
      "details": {
        "role_id": "role_123",
        "assigned_by": "admin_user_123"
      },
      "ip_address": "192.168.1.100",
      "user_agent": "Mozilla/5.0...",
      "timestamp": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

🔧 Configuration

RBAC Engine Setup

from recoagent.packages.security.rbac import RoleManager

# Initialize role manager
role_manager = RoleManager(
    audit_logging=True,
    permission_caching=True,
    cache_ttl=300  # 5 minutes
)

# Create roles
role_manager.create_role(
    name="admin",
    permissions=["*"],  # All permissions
    description="Administrator role"
)

role_manager.create_role(
    name="analyst",
    permissions=["data:read", "analytics:read", "models:read"],
    description="Data analyst role"
)

role_manager.create_role(
    name="viewer",
    permissions=["data:read"],
    description="Read-only viewer role"
)

Permission Definition

# Define permissions
permissions = [
    {
        "name": "data:read",
        "description": "Read access to data",
        "resource": "data",
        "action": "read"
    },
    {
        "name": "data:write",
        "description": "Write access to data",
        "resource": "data",
        "action": "write"
    },
    {
        "name": "models:create",
        "description": "Create new models",
        "resource": "models",
        "action": "create"
    }
]

# Register permissions
for perm in permissions:
    role_manager.create_permission(**perm)

📊 Permission Matrix

Resource	Create	Read	Update	Delete	Admin
Users	✅	✅	✅	✅	✅
Data	✅	✅	✅	✅	✅
Models	✅	✅	✅	✅	✅
Analytics	✅	✅	✅	❌	✅
Settings	❌	✅	✅	❌	✅

🛡️ Security Features

Permission Inheritance

• Role Hierarchy: Roles can inherit from other roles
• Permission Aggregation: User permissions from multiple roles
• Conditional Permissions: Context-aware permission evaluation
• Permission Caching: High-performance permission checking

Audit Logging

• Complete Audit Trail: All RBAC operations logged
• User Activity: Track user permission usage
• Role Changes: Monitor role assignments and modifications
• Security Events: Track security-related events

📚 Examples

Python SDK Usage

from recoagent_sdk import RecoAgentClient

# Initialize client
client = RecoAgentClient(
    api_key="sk-enterprise-123",
    base_url="https://api.recoagent.com/v2"
)

# Create role
role = client.rbac.roles.create({
    "name": "analyst",
    "description": "Data analyst role",
    "permissions": ["data:read", "analytics:read"]
})

# Assign role to user
assignment = client.rbac.users.assign_role(
    user_id="user_123",
    role_id=role.id,
    tenant_id="tenant_abc"
)

# Check permission
has_permission = client.rbac.check_permission(
    user_id="user_123",
    permission="data:read",
    resource_id="data_456"
)

print(f"Has permission: {has_permission}")

TypeScript SDK Usage

import { RecoAgentClient } from '@recoagent/sdk';

// Initialize client
const client = new RecoAgentClient({
  apiKey: 'sk-enterprise-123',
  baseUrl: 'https://api.recoagent.com/v2'
});

// Create role
const role = await client.rbac.roles.create({
  name: 'analyst',
  description: 'Data analyst role',
  permissions: ['data:read', 'analytics:read']
});

// Assign role to user
const assignment = await client.rbac.users.assignRole(
  'user_123',
  role.id,
  { tenantId: 'tenant_abc' }
);

// Check permission
const hasPermission = await client.rbac.checkPermission(
  'user_123',
  'data:read',
  { resourceId: 'data_456' }
);

console.log(`Has permission: ${hasPermission}`);

🎯 Next Steps

1. Design Role Hierarchy: Plan your organization's role structure
2. Define Permissions: Create granular permissions for resources
3. Configure Role Assignment: Set up automatic role assignment
4. Test Permissions: Validate permission checking functionality
5. Set Up Audit Logging: Enable comprehensive audit logging
6. Monitor RBAC Usage: Track role and permission usage

---

Secure your AI operations with enterprise-grade RBAC! 🔐