> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/org/role-permission.md). # 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 {% hint style="info" %} **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. {% endhint %} *** ### Role Type Descriptions MaiAgent platform roles are divided into three types: #### Owner Role **Definition:** The highest-permission role automatically granted to the organization creator {% hint style="info" %} **Simple explanation:** Like the company's "CEO" or "system administrator" — can manage everything, view all data, with no restrictions. {% endhint %} **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 {% hint style="warning" %} The owner role has the highest permissions. Assign it carefully and only to personnel who truly need to manage the entire system. {% endhint %} #### Default Role **Definition:** A base role automatically held by all organization members, giving members basic permissions before other roles are assigned {% hint style="info" %} **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. {% endhint %} **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) {% hint style="warning" %} **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." {% endhint %} #### Custom Role **Definition:** Roles manually or batch-assigned to specific members by administrators {% hint style="info" %} **Simple explanation:** Like the various "departments" or "positions" in a company (Customer Service, Marketing, Manager, etc.), with different permissions granted based on job requirements. {% endhint %} **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:** ``` Member's final permissions = Default Role permissions + All Custom Role permissions ``` **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 {% hint style="info" %} If using EIP login, roles can be automatically synced from the enterprise system. See [Third-Party Login (SSO)](/maiagent-user-guide/maiagent-user-guide-en/org/sso.md) for details. {% endhint %} *** ### 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](/maiagent-user-guide/maiagent-user-guide-en/org/member.md#advanced-operations-batch-member-and-permission-management))

Role permission settings diagram

{% hint style="info" %} **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 {% endhint %} *** ### Permission Levels MaiAgent uses a **hierarchical permission architecture** with permissions divided into **main permissions** and **sub-permissions**: {% hint style="info" %} **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 {% endhint %} #### Permission Structure Overview
Main PermissionSub-PermissionDescription
MaiGPT Permission-Controls access to MaiGPT features
AI Feature PermissionAI Assistant PermissionControls viewing and operations on the "AI Assistants" tab
Knowledge Base PermissionControls viewing and operations on the "Knowledge Bases" tab
Crawler PermissionControls access to crawler features
Tool PermissionControls access to tool management features
AgentOps PermissionTest Set PermissionControls viewing and operations on test set features
Automated Testing PermissionControls access to automated testing features
Customer Service Conversation PermissionAll Conversations PermissionControls viewing and operations on the "All Conversations" tab
Conversation Platform PermissionControls viewing and operations on the "Conversation Platforms" tab
Contact PermissionControls access to contact management features
Q&A Permission-Controls viewing and operations on the "Internal Q&A" tab
Developer PermissionAPI Call Log PermissionControls viewing of API call logs
Organization PermissionOrganization Overview PermissionControls viewing of the organization overview page
Activity Log PermissionControls viewing of activity log features
{% hint style="info" %} **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 {% endhint %} #### Permission Configuration Instructions 1. 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.
2. 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.

Left menu page

Role permission settings page

*** ### 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: 1. Navigate to the Assign Members page 2. Click the "+ Assign Members" button
3. Select the members to add and click the "Add >" button in the center 4. Click the "Confirm" button in the lower right to complete the configuration

Select members to add

Click Add

Addition complete, click Confirm

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:

Updated permission page

No permission notice

This way, the member can only use the AI assistant feature and cannot make any other changes. {% hint style="info" %} Need to batch-assign roles to multiple members? See [Member Management: Batch Member and Permission Management](/maiagent-user-guide/maiagent-user-guide-en/org/member.md#advanced-operations-batch-member-and-permission-management). {% endhint %} *** ### Assign AI Assistants You can restrict which AI assistants a role can use, ensuring knowledge base data is properly separated by role permissions: 1. Navigate to the "Assign AI Assistants" page 2. Click the "+ Assign AI Assistants" button
3. Select the AI assistants to add and click the "Add >" button in the center 4. Click the "Confirm" button in the lower right to complete the configuration

Select AI assistants to add

Click the center Add AI Assistant button

Addition complete, click Confirm

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:
{% hint style="info" %} The owner role automatically has access to all AI assistants without manual assignment. {% endhint %} *** ### Assign Knowledge Bases You can restrict which knowledge bases a role can access, ensuring sensitive data is only accessible to specific roles: 1. Navigate to the "Assign Knowledge Bases" page 2. Click the "+ Assign Knowledge Bases" button
3. Select the knowledge bases to add and click the "Add >" button in the center 4. 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 {% hint style="info" %} The owner role automatically has access to all knowledge bases without manual assignment. {% endhint %} *** ### Assign Conversation Platforms You can restrict which conversation platforms a role can use, assigning different teams to different customer service channels: 1. Navigate to the "Assign Conversation Platforms" page 2. Click the "+ Assign Conversation Platforms" button
3. Select the conversation platforms to add and click the "Add >" button in the center 4. 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 {% hint style="info" %} The owner role automatically has access to all conversation platforms without manual assignment. {% endhint %} *** ### 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. {% hint style="info" %} **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. {% endhint %} **Example:** ``` Member B has the following roles simultaneously: ├─ Customer Service Role: Q&A Permission + All Conversations Permission └─ Marketing Role: AI Feature Permission (AI Assistants) + All Conversations Permission → Member B's effective permissions: Q&A Permission + All Conversations Permission + AI Assistant Permission (Duplicate permissions are not stacked; they are counted only once) ```
#### Permission Application Order The system calculates permissions in the following order: ``` Step 1: Apply "Default Role" permissions ↓ (Automatic, all members have this) Step 2: Apply "Custom Role A" permissions ↓ (Administrator assigned) Step 3: Apply "Custom Role B" permissions ↓ (Administrator assigned) Final Permissions = Step 1 + Step 2 + Step 3 ```
1. **Default Role** (Automatically assigned) * Automatically generated when the organization is created * All users automatically have the default role permissions applied 2. **Custom Roles** (In assignment order) * Later-assigned roles are merged with existing permissions * They do not override existing permissions; they only add new ones {% hint style="warning" %} **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:** 1. Remove the member from the role, or 2. Modify the role's permission settings directly {% endhint %} #### Role Union Example **Scenario:** * The default role is associated with three AI assistants * A custom role is associated with only two AI assistants

Default Role

Custom Role

**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.
{% hint style="info" %} This is why it is recommended to set the default role's permissions to the minimum, to avoid affecting permission control for other roles. {% endhint %} #### 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:** ``` Member A's original permissions: Q&A + AI Features + Customer Service Conversations ↓ Remove "AI Feature Development" role ↓ Member A's effective permissions: Q&A + Customer Service Conversations ``` *** ### Troubleshooting #### Common Issue: User Cannot See Expected Features or Can Use More Features Than Expected 1. Check all roles the user belongs to, including whether the default role has too many permissions enabled 2. 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](/maiagent-user-guide/maiagent-user-guide-en/org/member.md#advanced-operations-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)](/maiagent-user-guide/maiagent-user-guide-en/org/sso.md)) #### 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/org/role-permission.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.