Permissions & Roles API
The Permissions & Roles API provides comprehensive role-based access control (RBAC) functionality for managing user permissions, roles, and authorization within the Oliver Chat system. This system supports both role-based permissions and individual permission assignments.
Enterprise Security: Our permission system is designed for enterprise environments with complex organizational structures, hierarchical access controls, and detailed audit requirements.
Permission System Overview
Oliver Chat implements a sophisticated permission system that combines:
🔐 Role-Based Permissions
Users are assigned roles that automatically grant a set of permissions. Roles can be customized and permissions can be grouped for easier management.
👤 Individual Permissions
Additional permissions can be granted or revoked for individual users, providing flexibility beyond role-based assignments.
📊 Permission Groups
Permissions are organized into logical groups (Chat, Images, RAG, Admin, etc.) for easier management and understanding.
🏢 Hierarchical Access
Supervisor relationships and organizational hierarchies are respected in permission evaluations and access controls.
List Permissions
Returns a list of all available permissions in the system, organized by groups.
GET
/api/v1/permissions
Authentication:
Required
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| group | string | No | Filter permissions by group |
| search | string | No | Search permissions by name or description |
| include_system | boolean | No | Include system-level permissions (default: false) |
Example Response
{
"success": true,
"data": {
"permissions": [
{
"id": 1,
"name": "Create Chats",
"key": "create_chats",
"group": "chat",
"description": "Allows creating new chat conversations",
"is_system": false,
"created_at": "2024-01-01T00:00:00Z"
},
{
"id": 2,
"name": "View Chats",
"key": "view_chats",
"group": "chat",
"description": "Allows viewing own chat conversations",
"is_system": false,
"created_at": "2024-01-01T00:00:00Z"
},
{
"id": 3,
"name": "Delete Chats",
"key": "delete_chats",
"group": "chat",
"description": "Allows deleting own chat conversations",
"is_system": false,
"created_at": "2024-01-01T00:00:00Z"
},
{
"id": 4,
"name": "Generate Images",
"key": "generate_images",
"group": "images",
"description": "Allows generating images with AI",
"is_system": false,
"created_at": "2024-01-01T00:00:00Z"
},
{
"id": 5,
"name": "View Generated Images",
"key": "view_generated_images",
"group": "images",
"description": "Allows viewing own generated images",
"is_system": false,
"created_at": "2024-01-01T00:00:00Z"
},
{
"id": 6,
"name": "Access RAG Containers",
"key": "access_rag_containers",
"group": "rag",
"description": "Allows accessing RAG document containers",
"is_system": false,
"created_at": "2024-01-01T00:00:00Z"
},
{
"id": 7,
"name": "Upload RAG Documents",
"key": "upload_rag_documents",
"group": "rag",
"description": "Allows uploading documents to RAG containers",
"is_system": false,
"created_at": "2024-01-01T00:00:00Z"
},
{
"id": 8,
"name": "Manage Users",
"key": "manage_users",
"group": "admin",
"description": "Allows creating and managing user accounts",
"is_system": false,
"created_at": "2024-01-01T00:00:00Z"
},
{
"id": 9,
"name": "View Compliance Reports",
"key": "view_compliance_reports",
"group": "compliance",
"description": "Allows viewing compliance reports and flags",
"is_system": false,
"created_at": "2024-01-01T00:00:00Z"
},
{
"id": 10,
"name": "Supervise Users",
"key": "supervise_users",
"group": "supervision",
"description": "Allows viewing supervised users' chats and activities",
"is_system": false,
"created_at": "2024-01-01T00:00:00Z"
}
],
"groups": [
{
"id": 1,
"name": "Chat",
"key": "chat",
"description": "Chat-related permissions",
"permission_count": 3
},
{
"id": 2,
"name": "Images",
"key": "images",
"description": "Image generation permissions",
"permission_count": 2
},
{
"id": 3,
"name": "RAG",
"key": "rag",
"description": "Retrieval-augmented generation permissions",
"permission_count": 2
},
{
"id": 4,
"name": "Admin",
"key": "admin",
"description": "Administrative permissions",
"permission_count": 1
},
{
"id": 5,
"name": "Compliance",
"key": "compliance",
"description": "Compliance and audit permissions",
"permission_count": 1
},
{
"id": 6,
"name": "Supervision",
"key": "supervision",
"description": "User supervision permissions",
"permission_count": 1
}
]
},
"message": "Permissions retrieved successfully"
}List Roles
Returns a list of all roles in the system with their associated permissions.
GET
/api/v1/roles
Authentication:
Required
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| include_permissions | boolean | No | Include detailed permission information (default: true) |
| include_user_count | boolean | No | Include count of users with each role (default: true) |
Example Response
{
"success": true,
"data": {
"roles": [
{
"id": 1,
"name": "Administrator",
"key": "admin",
"description": "Full system access with all administrative privileges",
"is_system": true,
"user_count": 5,
"permissions": [
{
"id": 1,
"name": "Create Chats",
"key": "create_chats",
"group": "chat"
},
{
"id": 2,
"name": "View Chats",
"key": "view_chats",
"group": "chat"
},
{
"id": 8,
"name": "Manage Users",
"key": "manage_users",
"group": "admin"
},
{
"id": 9,
"name": "View Compliance Reports",
"key": "view_compliance_reports",
"group": "compliance"
}
],
"created_at": "2024-01-01T00:00:00Z"
},
{
"id": 2,
"name": "Supervisor",
"key": "supervisor",
"description": "Can manage supervised users and view their activities",
"is_system": true,
"user_count": 12,
"permissions": [
{
"id": 1,
"name": "Create Chats",
"key": "create_chats",
"group": "chat"
},
{
"id": 2,
"name": "View Chats",
"key": "view_chats",
"group": "chat"
},
{
"id": 4,
"name": "Generate Images",
"key": "generate_images",
"group": "images"
},
{
"id": 10,
"name": "Supervise Users",
"key": "supervise_users",
"group": "supervision"
}
],
"created_at": "2024-01-01T00:00:00Z"
},
{
"id": 3,
"name": "Financial Advisor",
"key": "financial_advisor",
"description": "Standard user with financial tools access",
"is_system": true,
"user_count": 87,
"permissions": [
{
"id": 1,
"name": "Create Chats",
"key": "create_chats",
"group": "chat"
},
{
"id": 2,
"name": "View Chats",
"key": "view_chats",
"group": "chat"
},
{
"id": 4,
"name": "Generate Images",
"key": "generate_images",
"group": "images"
},
{
"id": 6,
"name": "Access RAG Containers",
"key": "access_rag_containers",
"group": "rag"
}
],
"created_at": "2024-01-01T00:00:00Z"
},
{
"id": 4,
"name": "Compliance Officer",
"key": "compliance_officer",
"description": "Specialized role for compliance monitoring and reporting",
"is_system": true,
"user_count": 8,
"permissions": [
{
"id": 1,
"name": "Create Chats",
"key": "create_chats",
"group": "chat"
},
{
"id": 2,
"name": "View Chats",
"key": "view_chats",
"group": "chat"
},
{
"id": 9,
"name": "View Compliance Reports",
"key": "view_compliance_reports",
"group": "compliance"
},
{
"id": 10,
"name": "Supervise Users",
"key": "supervise_users",
"group": "supervision"
}
],
"created_at": "2024-01-01T00:00:00Z"
}
]
},
"message": "Roles retrieved successfully"
}Create Role
Create a new role with specified permissions.
POST
/api/v1/roles
Authentication:
Required
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Role name (max 255 characters) |
| key | string | Yes | Unique role key (alphanumeric and underscores only) |
| description | string | No | Role description |
| permission_ids | array | Yes | Array of permission IDs to assign to this role |
| is_default | boolean | No | Whether this role should be assigned to new users by default |
Example Request
{
"name": "Junior Advisor",
"key": "junior_advisor",
"description": "Entry-level financial advisor role with limited permissions",
"permission_ids": [1, 2, 4, 6],
"is_default": false
}Example Response
{
"success": true,
"data": {
"role": {
"id": 5,
"name": "Junior Advisor",
"key": "junior_advisor",
"description": "Entry-level financial advisor role with limited permissions",
"is_system": false,
"is_default": false,
"user_count": 0,
"permissions": [
{
"id": 1,
"name": "Create Chats",
"key": "create_chats",
"group": "chat"
},
{
"id": 2,
"name": "View Chats",
"key": "view_chats",
"group": "chat"
},
{
"id": 4,
"name": "Generate Images",
"key": "generate_images",
"group": "images"
},
{
"id": 6,
"name": "Access RAG Containers",
"key": "access_rag_containers",
"group": "rag"
}
],
"created_at": "2025-03-11T16:30:00Z",
"updated_at": "2025-03-11T16:30:00Z"
}
},
"message": "Role created successfully"
}Update Role
Update an existing role's information and permissions.
PUT
/api/v1/roles/{role_id}
Authentication:
Required
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| role_id | integer | Yes | ID of the role to update |
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | No | Role name |
| description | string | No | Role description |
| permission_ids | array | No | Array of permission IDs (replaces existing permissions) |
| is_default | boolean | No | Whether this role should be assigned to new users by default |
Example Request
{
"name": "Senior Junior Advisor",
"description": "Entry-level financial advisor role with expanded permissions",
"permission_ids": [1, 2, 3, 4, 5, 6]
}Example Response
{
"success": true,
"data": {
"role": {
"id": 5,
"name": "Senior Junior Advisor",
"key": "junior_advisor",
"description": "Entry-level financial advisor role with expanded permissions",
"is_system": false,
"is_default": false,
"user_count": 0,
"permissions": [
{
"id": 1,
"name": "Create Chats",
"key": "create_chats",
"group": "chat"
},
{
"id": 2,
"name": "View Chats",
"key": "view_chats",
"group": "chat"
},
{
"id": 3,
"name": "Delete Chats",
"key": "delete_chats",
"group": "chat"
},
{
"id": 4,
"name": "Generate Images",
"key": "generate_images",
"group": "images"
},
{
"id": 5,
"name": "View Generated Images",
"key": "view_generated_images",
"group": "images"
},
{
"id": 6,
"name": "Access RAG Containers",
"key": "access_rag_containers",
"group": "rag"
}
],
"updated_at": "2025-03-11T16:45:00Z"
}
},
"message": "Role updated successfully"
}Get User Permissions
Get detailed information about a user's permissions, including role-based and individual permissions.
GET
/api/v1/users/{user_id}/permissions
Authentication:
Required
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| user_id | integer | Yes | ID of the user |
Example Response
{
"success": true,
"data": {
"user": {
"id": 45,
"name": "John Smith",
"email": "jsmith@advisorsassetmanagement.com"
},
"roles": [
{
"id": 3,
"name": "Financial Advisor",
"key": "financial_advisor"
}
],
"permissions": {
"role_permissions": [
{
"id": 1,
"name": "Create Chats",
"key": "create_chats",
"group": "chat",
"source": "role:financial_advisor"
},
{
"id": 2,
"name": "View Chats",
"key": "view_chats",
"group": "chat",
"source": "role:financial_advisor"
},
{
"id": 4,
"name": "Generate Images",
"key": "generate_images",
"group": "images",
"source": "role:financial_advisor"
},
{
"id": 6,
"name": "Access RAG Containers",
"key": "access_rag_containers",
"group": "rag",
"source": "role:financial_advisor"
}
],
"individual_permissions": [
{
"id": 7,
"name": "Upload RAG Documents",
"key": "upload_rag_documents",
"group": "rag",
"source": "individual",
"granted_by": "Admin User",
"granted_at": "2025-02-15T10:30:00Z"
},
{
"id": 10,
"name": "Supervise Users",
"key": "supervise_users",
"group": "supervision",
"source": "individual",
"granted_by": "Admin User",
"granted_at": "2025-03-01T14:15:00Z"
}
],
"denied_permissions": [
{
"id": 8,
"name": "Manage Users",
"key": "manage_users",
"group": "admin",
"source": "individual",
"denied_by": "Admin User",
"denied_at": "2025-02-20T09:45:00Z",
"reason": "Not authorized for user management functions"
}
],
"effective_permissions": [
"create_chats",
"view_chats",
"generate_images",
"access_rag_containers",
"upload_rag_documents",
"supervise_users"
]
},
"permission_summary": {
"total_permissions": 6,
"role_granted": 4,
"individually_granted": 2,
"individually_denied": 1
}
},
"message": "User permissions retrieved successfully"
}Update User Permissions
Grant or revoke individual permissions for a specific user (in addition to their role permissions).
PATCH
/api/v1/users/{user_id}/permissions
Authentication:
Required
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| user_id | integer | Yes | ID of the user |
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| grant_permissions | array | No | Array of permission IDs to grant to the user |
| revoke_permissions | array | No | Array of permission IDs to revoke from the user |
| deny_permissions | array | No | Array of permission IDs to explicitly deny (overrides role permissions) |
| reason | string | No | Reason for the permission changes (for audit purposes) |
Example Request
{
"grant_permissions": [7, 10],
"deny_permissions": [8],
"reason": "User promoted to team lead role - granted RAG upload and supervision permissions, but not full admin access"
}Example Response
{
"success": true,
"data": {
"user": {
"id": 45,
"name": "John Smith",
"email": "jsmith@advisorsassetmanagement.com"
},
"changes": {
"granted": [
{
"id": 7,
"name": "Upload RAG Documents",
"key": "upload_rag_documents",
"group": "rag"
},
{
"id": 10,
"name": "Supervise Users",
"key": "supervise_users",
"group": "supervision"
}
],
"denied": [
{
"id": 8,
"name": "Manage Users",
"key": "manage_users",
"group": "admin"
}
],
"revoked": []
},
"effective_permissions": [
"create_chats",
"view_chats",
"generate_images",
"access_rag_containers",
"upload_rag_documents",
"supervise_users"
],
"audit_entry": {
"action": "permissions_updated",
"reason": "User promoted to team lead role - granted RAG upload and supervision permissions, but not full admin access",
"timestamp": "2025-03-11T17:00:00Z"
}
},
"message": "User permissions updated successfully"
}Check Permission
Check if a user has a specific permission or set of permissions.
POST
/api/v1/users/{user_id}/permissions/check
Authentication:
Required
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| user_id | integer | Yes | ID of the user |
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| permissions | array | Yes | Array of permission keys to check |
| require_all | boolean | No | Whether user must have ALL permissions (true) or ANY permission (false, default) |
Example Request
{
"permissions": ["create_chats", "generate_images", "manage_users"],
"require_all": false
}Example Response
{
"success": true,
"data": {
"user": {
"id": 45,
"name": "John Smith",
"email": "jsmith@advisorsassetmanagement.com"
},
"permission_check": {
"has_access": true,
"require_all": false,
"results": {
"create_chats": {
"has_permission": true,
"source": "role:financial_advisor"
},
"generate_images": {
"has_permission": true,
"source": "role:financial_advisor"
},
"manage_users": {
"has_permission": false,
"source": "denied:individual",
"reason": "Explicitly denied individual permission"
}
},
"summary": {
"permissions_checked": 3,
"permissions_granted": 2,
"permissions_denied": 1
}
}
},
"message": "Permission check completed successfully"
}Permission Inheritance & Hierarchies
Oliver Chat supports sophisticated permission inheritance based on organizational hierarchies:
Supervisor Access: Users with supervision permissions can access certain information about their supervised users, including chat history and activity logs, regardless of the supervised user's individual permissions.
System Permissions
Some permissions are considered "system-level" and can only be managed by administrators:
- System Administration: Core system configuration and maintenance
- Security Management: Security settings and encryption key management
- Audit Access: Full audit log access and compliance reporting
- User Management: Creating, modifying, and deactivating user accounts
- Role Management: Creating and modifying roles and permissions
API Tester
Test the Permissions & Roles API endpoints directly from this documentation.