Role Permission Management
Role Concept
A Role is a functional unit within the organization with freely configurable member composition:
Members assigned to a role can come from any member within the organization
A single member can inherit multiple roles simultaneously, enabling flexible permission management
Each role has independent permission settings to accommodate different scenarios
Simple explanation:
A role is like a company "department" or "position," such as Customer Service, Marketing, or Manager. You first define what each department can do, then add employees to the corresponding department.
Role Type Descriptions
MaiAgent platform roles are divided into three types:
Owner Role
Definition: The highest-permission role automatically granted to the organization creator
Simple explanation:
Like the company's "CEO" or "system administrator" — can manage everything, view all data, with no restrictions.
Characteristics:
Has full access to all resources without additional assignment
Can manage all settings within the organization, including roles, members, and permissions
An organization can have multiple owners
The owner role can be assigned to or removed from other members
The owner role has the highest permissions. Assign it carefully and only to personnel who truly need to manage the entire system.
Default Role
Definition: A base role automatically held by all organization members, giving members basic permissions before other roles are assigned
Simple explanation:
Like a company "employee badge" — everyone automatically gets one when they join the company, ensuring new hires can use basic features without waiting for configuration.
Characteristics:
All organization members automatically receive the default role's permissions
Provides the most basic platform access permissions (such as Q&A functionality)
Cannot be batch-assigned via Excel
Administrators can customize the default role's permission scope
Members cannot be manually assigned (the system automatically assigns it to all members)
Recommended configuration:
The default role should only have "minimum" permissions to prevent new members from making accidental changes. Other permissions should be distributed through "custom roles."
Custom Role
Definition: Roles manually or batch-assigned to specific members by administrators
Simple explanation:
Like the various "departments" or "positions" in a company (Customer Service, Marketing, Manager, etc.), with different permissions granted based on job requirements.
Characteristics:
Requires active assignment by an administrator
Different permission combinations can be configured for different responsibilities
Supports batch assignment for convenient large-scale member management
Members immediately receive corresponding permissions upon assignment
Permission calculation method:
Example:
Member A is assigned to the "Customer Service" role → Gains Q&A permissions + Conversation permissions
Member A is also assigned to the "Testing Team" role → Additionally gains AgentOps permissions
Member A's final permissions: Default permissions + Customer Service permissions + Testing Team permissions
If using EIP login, roles can be automatically synced from the enterprise system. See Third-Party Login (SSO) for details.
Editing Role Permissions
Within the organization, you can click "Edit Role Permissions" to configure permissions for members of that role.
On the role permissions page, you can:
Add Role: Create a role for the organization (e.g., Marketing Department). When new members join, applying the role automatically grants them the corresponding permissions
Edit Role: Modify role name, description, or department information
Role Permissions: Configure the feature modules and operation scope available to the role
Assign Members: Add organization members to the specified role for unified permission management
Assign AI Assistants: Assign AI assistants the role can operate
Assign Knowledge Bases: Assign knowledge bases the role can access
Assign Conversation Platforms: Assign conversation platforms the role can use
Delete Role: Remove roles that are no longer in use to keep the organization's permission structure clean
Batch Features: Batch add members to the organization or batch assign roles to members via Excel (see Member Management: Batch Member and Permission Management)
Role settings tab notes
Owner Role: The "Assign AI Assistants," "Assign Knowledge Bases," and "Assign Conversation Platforms" tabs are disabled because the owner role automatically has access to all resources
Default Role: The "Assign Members" tab is disabled because the default role is automatically assigned to all members
Permission Levels
MaiAgent uses a hierarchical permission architecture with permissions divided into main permissions and sub-permissions:
What is a "hierarchical permission architecture"?
It is like a folder structure:
Main permission = Main folder (e.g., "AI Features")
Sub-permission = Subfolder (e.g., "AI Assistants," "Knowledge Bases," "Crawlers")
How it works:
Checking a main permission automatically includes all sub-permissions
You can also check only specific sub-permissions for more granular control
Permission Structure Overview
MaiGPT Permission
-
Controls access to MaiGPT features
AI Feature Permission
AI Assistant Permission
Controls viewing and operations on the "AI Assistants" tab
Knowledge Base Permission
Controls viewing and operations on the "Knowledge Bases" tab
Crawler Permission
Controls access to crawler features
Tool Permission
Controls access to tool management features
AgentOps Permission
Test Set Permission
Controls viewing and operations on test set features
Automated Testing Permission
Controls access to automated testing features
Customer Service Conversation Permission
All Conversations Permission
Controls viewing and operations on the "All Conversations" tab
Conversation Platform Permission
Controls viewing and operations on the "Conversation Platforms" tab
Contact Permission
Controls access to contact management features
Q&A Permission
-
Controls viewing and operations on the "Internal Q&A" tab
Developer Permission
API Call Log Permission
Controls viewing of API call logs
Organization Permission
Organization Overview Permission
Controls viewing of the organization overview page
Activity Log Permission
Controls viewing of activity log features
Permission level notes
Checking a main permission automatically includes all sub-permissions under it
You can also check only specific sub-permissions for more granular permission control
A user's final permissions are the sum of the system default role and custom role permissions
Permission Configuration Instructions
Add a role and assign permissions
Click "Add Role" in the upper right corner to enter a name for the new role and check the permissions the role should have.
Edit name and permissions
Enter the editing page to edit the role name and re-check the permissions the role should have.
Based on the role definition, you can decide whether organization members can view or use related feature tabs in the left menu. Use checkboxes to enable/disable each permission, then click the "Save" button in the lower right to apply the settings.
Permission Use Cases
Suppose an enterprise uses MaiAgent to build a customer service system:
Scenario 1: New Customer Service Agent
Grant only "Q&A Permission"
Reason: They just joined and need to quickly learn product knowledge and company policies
Prevention: Prevents the agent from accidentally deleting customer conversation records or modifying important AI assistant settings while still unfamiliar
Scenario 2: Senior Customer Service Agent
"Q&A Permission" + "Customer Service Conversation Permission (All Conversations)"
Reason: Experienced and needs to help handle complex complaints and guide new agents
Prevention: AI feature permissions are still withheld to prevent service agents from accidentally modifying AI assistant settings, which could cause all customers to receive incorrect responses
Scenario 3: AI Assistant Administrator
"AI Feature Permission" + "AgentOps Permission"
Reason: Responsible for managing and optimizing AI assistant response quality
Prevention: Customer service conversation permissions are withheld to avoid access to customer privacy data
Assign Members
You can assign created roles to members in your organization:
Navigate to the Assign Members page
Click the "+ Assign Members" button
Select the members to add and click the "Add >" button in the center
Click the "Confirm" button in the lower right to complete the configuration
The newly added members will appear in the member list.
After addition, since the member only has AI assistant permissions, the left menu will only show the AI assistant feature menu. Other features like customer service conversations and organization settings will not appear in the left menu. When a member navigates to a feature they do not have permission to access, a no-permission notice will appear:
This way, the member can only use the AI assistant feature and cannot make any other changes.
Need to batch-assign roles to multiple members? See Member Management: Batch Member and Permission Management.
Assign AI Assistants
You can restrict which AI assistants a role can use, ensuring knowledge base data is properly separated by role permissions:
Navigate to the "Assign AI Assistants" page
Click the "+ Assign AI Assistants" button
Select the AI assistants to add and click the "Add >" button in the center
Click the "Confirm" button in the lower right to complete the configuration
After addition, the selected AI assistants will appear in the list:
After completion, users with this role can only view and use the assigned AI assistants:
The owner role automatically has access to all AI assistants without manual assignment.
Assign Knowledge Bases
You can restrict which knowledge bases a role can access, ensuring sensitive data is only accessible to specific roles:
Navigate to the "Assign Knowledge Bases" page
Click the "+ Assign Knowledge Bases" button
Select the knowledge bases to add and click the "Add >" button in the center
Click the "Confirm" button in the lower right to complete the configuration
After addition, the selected knowledge bases will appear in the list.
Use cases:
R&D Department: Can only access technical documentation knowledge bases
Sales Department: Can only access product description and pricing knowledge bases
HR Department: Can only access employee handbook knowledge bases
The owner role automatically has access to all knowledge bases without manual assignment.
Assign Conversation Platforms
You can restrict which conversation platforms a role can use, assigning different teams to different customer service channels:
Navigate to the "Assign Conversation Platforms" page
Click the "+ Assign Conversation Platforms" button
Select the conversation platforms to add and click the "Add >" button in the center
Click the "Confirm" button in the lower right to complete the configuration
After addition, the selected conversation platforms will appear in the list.
Use cases:
LINE Customer Service Team: Can only access the LINE conversation platform
Website Customer Service Team: Can only access the Web Chat conversation platform
VIP Customer Service Team: Can access all conversation platforms
The owner role automatically has access to all conversation platforms without manual assignment.
Default Role
The default role is automatically generated when the organization is created and serves as the base role for all users. When applying user role configurations, if no specific role is assigned, the system will automatically apply all permission settings from the default role.
It is recommended to set the default role permissions to the minimum level to prevent default role settings from overriding other role configurations
Permission Handling
When a user is assigned to multiple roles simultaneously, MaiAgent uses the following permission handling logic:
Permission Union Principle
Uses the "maximum permission" strategy: The user will receive the union of all role permissions, meaning they will have the broadest possible operation permissions.
Simple explanation:
When a member belongs to multiple roles simultaneously, they receive the union of all role permissions rather than only the permissions of a single role.
Example:
Permission Application Order
The system calculates permissions in the following order:
Default Role (Automatically assigned)
Automatically generated when the organization is created
All users automatically have the default role permissions applied
Custom Roles (In assignment order)
Later-assigned roles are merged with existing permissions
They do not override existing permissions; they only add new ones
Key points:
Later-assigned roles "do not override" existing permissions
They only "add" more permissions
You cannot "reduce" permissions by assigning new roles
To reduce someone's permissions, you must:
Remove the member from the role, or
Modify the role's permission settings directly
Role Union Example
Scenario:
The default role is associated with three AI assistants
A custom role is associated with only two AI assistants
Result: Even if the user has been assigned to the custom role, the union still includes the default role's associated settings, so the user can ultimately use three AI assistants.
This is why it is recommended to set the default role's permissions to the minimum, to avoid affecting permission control for other roles.
Permission Removal
When a user is removed from a role:
Removing a custom role: Loses that role's specific permissions; retains other role permissions
Cannot remove the default role: All users permanently belong to the default role
Permission check: The system recalculates the user's effective permissions
Example:
Troubleshooting
Common Issue: User Cannot See Expected Features or Can Use More Features Than Expected
Check all roles the user belongs to, including whether the default role has too many permissions enabled
Ask the user to clear browser cache and log in again
Permission Audit Recommendations
Regularly review whether user role assignments are appropriate
Remove all role assignments for departed members
FAQ
Q: How do I give new members more permissions?
Administrators can assign additional roles to members through the following methods:
Individual member: Click the member in the member list and manually add roles
Batch assignment: Use the Member Management: Batch Member and Permission Management feature to assign roles to multiple people at once via Excel
EIP auto-sync: If using EIP login, roles can be configured on the EIP side and automatically synced during login (Third-Party Login (SSO))
Q: Why can't the default role be batch-assigned via Excel?
The default role is a base role automatically held by all members. The system automatically assigns it to every member, so it does not need to be and cannot be assigned via Excel.
Q: Why can't the owner role be assigned AI assistants, knowledge bases, or conversation platforms?
The owner role has full access to all resources without additional assignment. The system automatically grants the owner role access to all resources within the organization.
Q: What does the hierarchical permission structure mean?
MaiAgent's permissions use a parent-child hierarchy. For example, "AI Feature Permission" is a main permission that includes sub-permissions like "AI Assistant Permission," "Knowledge Base Permission," "Crawler Permission," and "Tool Permission." Checking a main permission automatically includes all sub-permissions, but you can also check only specific sub-permissions for more granular control.
Last updated
Was this helpful?