> 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/en/org/roles/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 (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 (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 (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/en/org/sso.md) for details. {% endhint %} *** ### Edit Role Permissions Within the organization, 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 * Assign Skills: Assign the skills the role can read, configure read/edit/delete permissions for each skill, and specify whether new skills can be added (see [Skill Management: Control Skill Visibility and Permissions by Role](/maiagent-user-guide/en/skills/skills-management.md#skill-role-visibility)) * 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](https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/pages/gEVCBLlgrbsFwGlsxU0f#進階操作批次成員與權限管理))

{% hint style="info" %} **Role settings tab notes** * **Owner Role**: Resource assignment tabs such as "Assign AI Assistants," "Assign Knowledge Bases," "Assign Conversation Platforms," and "Assign Skills" 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 Permission	Sub-Permission	Description
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
Agent Marketplace Permission	-	Controls viewing and operations on the "Agent Marketplace" tab
AI Gateway Permission	-	Controls whether AI Gateway appears in the left menu and whether members can access its pages
Meeting Records Permission	Live Transcription Permission	Controls whether users can create new meetings and start recording
Meeting List Permission	Controls whether users can view the meeting list and details, and download meetings
Meeting Record Management Permission	-	Controls the meeting records users can view: when unchecked, users can only view meetings they participated in; when checked, users can view all meetings in the organization (see Meeting Access Permissions)
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

{% 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. #### Enable AI Gateway for a Specific Role If only model administrators in your company need access to AI Gateway, enable the permission only for their role: 1. Go to Organization Settings, then open Role Permissions. 2. To create a role, click Add Role and enter a role name. You can also edit the Role Permissions of an existing role. 3. Check AI Gateway Permission, then click Confirm. In the English interface, the button is labeled OK. 4. Assign the model administrators to this role. After members sign back in to the admin console, AI Gateway appears in the left menu. Members without this permission cannot see the menu or directly access the related pages, and the system also rejects their AI Gateway API requests.

AI Gateway Permission selected in the role permissions dialog — Select AI Gateway Permission so members with this role can see and access AI Gateway

{% hint style="info" %} A member's final permissions are the sum of the default role and all custom-role permissions. If a member can still see AI Gateway, check their other assigned roles as well. {% endhint %}

*** ### 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

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. {% hint style="info" %} Need to batch-assign roles to multiple members? See [Member Management: Batch Member and Permission Management](https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/pages/gEVCBLlgrbsFwGlsxU0f#進階操作批次成員與權限管理). {% 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

Click the center Add AI Assistant button

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 (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 * Default role permissions are automatically applied to all users 2. **Custom roles** (in assignment order) * Roles assigned later are combined with existing permissions * They do not override existing permissions; they only add permissions {% hint style="warning" %} **Key points:** * Roles assigned later **do not override** existing permissions * They only **add** more permissions * You cannot **reduce** permissions by assigning a new role **To reduce someone's permissions, you must:** 1. Remove the member from that role, or 2. Modify the role's permission settings {% endhint %} #### Role Union Example **Scenario:** * The default role is associated with three AI assistants * The custom role is associated with only two AI assistants

**Result:** Even if the user has been assigned to the custom role, their permissions still include the settings associated with the default role, allowing them to use all three AI assistants.

{% hint style="info" %} This is why we recommend setting the default role's permissions to the minimum to avoid affecting permission controls for other roles. {% endhint %} #### Permission Removal When a user is removed from a role: * **Custom role removed**: The user loses the permissions specific to that role but retains permissions from other roles * **Default role cannot be removed**: All users always 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 the "AI Feature Development" role ↓ Member A's effective permissions: Q&A + Customer Service Conversations ``` *** ### Troubleshooting #### Common Issue: A User Cannot See Expected Features or Can Use Features Beyond What Is Expected 1. Check all roles the user belongs to, including whether the default role has been granted excessive permissions 2. Ask the user to clear their browser cache and log in again #### Permission Audit Recommendations * Regularly review whether user role assignments are appropriate * Remove all role assignments from former members *** ### FAQ #### Q: How Can I Give New Members More Permissions? Administrators can assign additional roles to members in the following ways: * **Individual member**: Click the member in the member list and manually add roles * **Batch assignment**: Use the [Member Management: Batch Member and Permission Management](https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/pages/gEVCBLlgrbsFwGlsxU0f#進階操作批次成員與權限管理) feature to assign roles to multiple people at once through Excel * **EIP automatic synchronization**: If you log in with EIP, configure roles on the EIP side to synchronize them automatically at login ([Third-Party Login (SSO)](/maiagent-user-guide/en/org/sso.md)) #### Q: Why Can't the Default Role Be Assigned in Batches Through Excel? The default role is the base role automatically granted to all members. The system assigns it to every member automatically, so it neither needs nor allows assignment through Excel. #### Q: Why Can't AI Assistants, Knowledge Bases, or Conversation Platforms Be Assigned to the Owner Role? The owner role has full access to all resources and does not require additional assignments. The system automatically grants the owner role access to every resource in the organization. #### Q: What Does the Permission Hierarchy Mean? MaiAgent permissions use a parent-child hierarchy. For example, "AI Feature Permission" is a parent permission that includes child permissions such as "AI Assistant Permission," "Knowledge Base Permission," "Crawler Permission," and "Tool Permission." Selecting a parent permission automatically includes all of its child permissions, or you can select only specific child 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/en/org/roles/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.