Role-Based Access Control

Configure role-based access control and tool filtering for your Diosc assistant.

Overview

Role-based access control (RBAC) allows you to customize the AI assistant's behavior and capabilities based on the user's role. This enables:

• Tool filtering: Control which backend APIs/tools each role can access
• Prompt customization: Add role-specific instructions to guide AI behavior
• Least-privilege access: Users only get the tools they need
• Compliance: Satisfy audit requirements for access control

When to Use Roles

Use roles when you have:

• Multiple user types with different permissions (admin, user, viewer)
• Compliance requirements for access segregation
• Department-specific tools (HR tools only for HR role)
• Need to prevent unauthorized actions (prevent viewers from deleting data)

Core Concepts

Roles Layer on Top of BYOA

Important: Roles are a layer ON TOP of the BYOA (Bring Your Own Auth) system:

1. User authenticates with your system (JWT, OAuth, etc.)
2. User's authentication credentials are forwarded to backend APIs
3. Roles add an additional filter: "Which tools can the AI even attempt to call?"

Roles do NOT replace authentication - they filter tool availability before the AI can invoke them.

Tool Access Control

Each role has two fields that control tool access:

allowAllTools (boolean, default: true)

• If true, the role can access every available tool
• If false, only tools listed in allowedToolNames are accessible

allowedToolNames (string[], default: [])

• Explicit list of tool names the role can use
• Only applies when allowAllTools is false
• Uses exact name matching (no wildcards or patterns)

Example:

{
  "allowAllTools": false,
  "allowedToolNames": ["get_user", "search_orders", "list_reports"]
}

Result: The role can only access these three specific tools.

Setting Up Roles

Via Admin API (REST)

Create a role:

POST /admin/assistants/{assistantId}/roles
Content-Type: application/json
X-Admin-Token: your-admin-token

{
  "assistantId": "ast_abc123",
  "roleName": "viewer",
  "displayName": "Read-Only Viewer",
  "promptInstructions": "You are assisting a viewer with read-only access. Do not suggest any modifications or deletions.",
  "allowAllTools": false,
  "allowedToolNames": ["get_user", "get_order", "search_orders", "search_customers", "list_reports"],
  "priority": 10
}

Via MCP Admin Server (Natural Language)

If you have Claude Desktop configured with the MCP Admin Server:

Create a viewer role:

Create a viewer role for assistant ast_abc123 that can only use read operations like get, search, and list

Common Role Examples

Read-Only Viewer

{
  "roleName": "viewer",
  "displayName": "Read-Only Viewer",
  "promptInstructions": "You are assisting a viewer with read-only access.",
  "allowAllTools": false,
  "allowedToolNames": ["get_user", "get_order", "search_orders", "search_customers", "list_reports", "view_dashboard"]
}

Standard User

{
  "roleName": "user",
  "displayName": "Standard User",
  "promptInstructions": "You are assisting a standard user. Most operations are available except deletions and admin functions.",
  "allowAllTools": false,
  "allowedToolNames": [
    "get_user", "get_order", "search_orders", "search_customers",
    "create_order", "update_order", "create_ticket"
  ]
}

Department-Scoped (HR Example)

{
  "roleName": "hr_staff",
  "displayName": "HR Staff Member",
  "promptInstructions": "You are assisting an HR staff member. Focus on employee-related tasks.",
  "allowAllTools": false,
  "allowedToolNames": [
    "get_employee", "search_employees", "update_employee",
    "get_hr_report", "create_hr_ticket"
  ]
}

Administrator

{
  "roleName": "admin",
  "displayName": "System Administrator",
  "promptInstructions": "You are assisting a system administrator with full access.",
  "allowAllTools": true
}

Role Resolution

How Roles Are Determined

Roles are resolved in this order:

1. MCP Role Resolver (if configured) - External system determines role
2. Client-Provided Roles - From authContext.roles
3. Default Role - Fallback (default: "default")

Configure MCP Role Resolver

POST /admin/assistants/{assistantId}/role-resolver
Content-Type: application/json

{
  "mcpServerId": "mcp_your_auth_system",
  "defaultRole": "user"
}

Your MCP server must expose: POST /resolve-role → Returns { "role": "role_name" }

Client-Provided Roles

diosc('auth', async () => ({
  headers: { 'Authorization': `Bearer ${token}` },
  userId: getCurrentUserId(),
  roles: ['viewer']
}));

Prompt Instructions by Role

The promptInstructions field adds role-specific AI guidance:

Example:

You are assisting a viewer with read-only access. Focus on retrieving information. Do not suggest modifications or deletions. If asked to perform write operations, explain that viewers can only view data.

Best Practices:

• Be specific about capabilities
• Keep it concise (2-4 sentences)
• Align with allowed tools

Testing Roles

1. Create test session with role
2. Verify denied tools are filtered out
3. Ask AI: "What can you help me with?"
4. Check logs for role resolution

Best Practices

1. Start restrictive, expand as needed
2. Use descriptive role names - viewer, hr_manager not role1
3. Document purposes - Use displayName and metadata
4. Audit assignments - Regularly review roles
5. Layer security - Roles + BYOA + Backend Auth + Approvals
6. Test after changes - Verify behavior
7. Version control configs - Export and store

API Reference

Method	Endpoint	Description
GET	/admin/assistants/{id}/roles	List all roles
POST	/admin/assistants/{id}/roles	Create role
PATCH	/admin/assistants/{id}/roles/{roleName}	Update role
DELETE	/admin/assistants/{id}/roles/{roleName}	Delete role
GET	/admin/assistants/{id}/role-resolver	Get resolver config
POST	/admin/assistants/{id}/role-resolver	Set resolver

---

Next: Approval Policies