> 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 permission management: the three role types, creating roles, selecting feature permissions, assigning resources such as AI assistants, knowledge bases, and conversation platforms, and a checklist

On this page: [Role concepts](#role-concept)｜[Role types](#role-types)｜[Edit role permissions](#edit-role-permissions)｜[Permission hierarchy](#permission-levels)｜[Permission use cases](#permission-use-cases)｜[Assign members](#assign-members)｜[Assign AI assistants](#assign-chatbots)｜[Assign teams](#assign-teams)｜[Assign knowledge bases](#assign-knowledge-bases)｜[Assign conversation platforms](#assign-inboxes)｜[Assign databases, tools, and Agent UI tools](#assign-databases-tools)｜[Filter and hide official built-in assistants in assignment dialogs](#assign-picker-filters)｜[Select all and remove in assignment dialogs](#assign-picker-select-remove)｜[Default role](#default-role-setting)｜[Permission handling](#permission-handling)｜[Troubleshooting](#troubleshooting)｜[FAQ](#faq)

## Role Concepts <a href="#role-concept" id="role-concept"></a>

A **role** is a functional unit within an organization. You can freely choose its members:

* Any member of the organization can be assigned to a role
* A member can inherit multiple roles at the same time for flexible permission management
* Each role has its own permission settings to meet different needs

{% hint style="info" %}
**A simple way to understand roles:**

Roles are like company departments or positions, such as customer service, marketing, or manager. First define what each department can do, then add employees to the appropriate department.
{% endhint %}

***

## Role Types <a href="#role-types" id="role-types"></a>

The MaiAgent platform has three types of roles:

### Owner Role <a href="#owner-role" id="owner-role"></a>

**Definition:** The role with the highest permissions, automatically granted to the organization creator

{% hint style="info" %}
**A simple way to understand this role:**

Like a company's general manager or system administrator, an owner can manage everything and view all data without restrictions.
{% endhint %}

**Features:**

* Has full access to all resources without additional assignments
* Can manage all organization settings, 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 people who need to manage the entire system.
{% endhint %}

### Default Role <a href="#default-role" id="default-role"></a>

**Definition:** A basic role automatically granted to all organization members, giving them basic permissions before any other roles are assigned

{% hint style="info" %}
**A simple way to understand this role:**

Like an employee ID card, everyone receives it automatically when they join the company. New employees can use basic features without waiting for setup.
{% endhint %}

**Features:**

* All organization members automatically receive the default role's permissions
* Provides basic platform access, such as Q\&A features
* Cannot be assigned in bulk through Excel
* Administrators can customize the default role's permissions
* Cannot grant [File Library](https://docs.maiagent.ai/maiagent-user-guide/en/work/file-library.md) permissions: by default, only owners can use the File Library. To give members access, create a custom role and grant it File Library permissions
* Members cannot be assigned manually (the system automatically assigns this role to all members)

{% hint style="warning" %}
**Recommended setup:**

Give the default role only the minimum permissions to prevent new members from making accidental changes. Assign additional permissions through custom roles.
{% endhint %}

### Custom Role <a href="#custom-role" id="custom-role"></a>

**Definition:** A role that administrators assign to specific members manually or in bulk

{% hint style="info" %}
**A simple way to understand this role:**

Like a company's departments or positions (customer service, marketing, managers, and so on), custom roles provide different permissions based on job requirements.
{% endhint %}

**Features:**

* Requires an administrator to assign it explicitly
* Supports different permission combinations for different responsibilities
* Supports bulk assignment to simplify managing large numbers of members
* Members receive the corresponding permissions immediately after assignment

**How permissions are calculated:**

```
Member's final permissions = Default role permissions + All custom role permissions
```

**Example:**

* Member A is assigned the Customer Service role → Receives Agent Marketplace permissions + Conversation permissions
* Member A is also assigned the Test Team role → Gains AgentOps permissions as well
* Member A's final permissions: Default permissions + Customer Service permissions + Test Team permissions

{% hint style="info" %}
If you use EIP login, roles can be synced automatically from your enterprise system. See [Third-party Login (SSO)](https://docs.maiagent.ai/maiagent-user-guide/en/org/sso.md).
{% endhint %}

***

## Edit Role Permissions <a href="#edit-role-permissions" id="edit-role-permissions"></a>

Access the role permissions page from Organization Overview: in the left menu, click <mark style="color:blue;">Organization Settings</mark> → <mark style="color:blue;">Organization Overview</mark>, then click <mark style="color:blue;">Edit Role Permissions</mark> in the <mark style="color:blue;">Management Actions</mark> section. The page lists all roles in the organization.

On the role permissions page, you can:

* <mark style="color:blue;">Add Role</mark>: Create an organization role, such as Marketing. Assign the role to new members to automatically give them the corresponding permissions
* <mark style="color:blue;">Duplicate</mark>: Create a new role using an existing custom role as a template. See [Duplicate a role](#duplicate-role)
* <mark style="color:blue;">Edit</mark>: Open the role settings page, which contains the following tabs in order
  * <mark style="color:blue;">Role Permissions</mark>: Set the feature modules and operations available to the role
  * <mark style="color:blue;">Assign Members</mark>: Add organization members to the role to manage their permissions together
  * <mark style="color:blue;">Assign MaiGPT Permissions</mark>: Set the models, features, tools, skills, and connectors this role can use in MaiGPT (see [MaiGPT Role Permissions](https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/maigpt-role-permissions.md))
  * <mark style="color:blue;">Assign AI Assistants</mark>: Assign the Agents the role can operate
  * <mark style="color:blue;">Assign Teams</mark>: Set the teams the role can use, view conversation history for, edit, or delete. See [Assign teams](#assign-teams)
  * <mark style="color:blue;">Assign Knowledge Bases</mark>: Assign the knowledge bases the role can access
  * <mark style="color:blue;">Assign Databases</mark>: Assign the databases the role can access. See [Assign databases](#assign-databases)
  * <mark style="color:blue;">Assign Tools</mark>: Assign the tools the role can attach to Agents. See [Assign tools](#assign-tools)
  * <mark style="color:blue;">Assign Agent UI Tools</mark>: Assign the Agent UI tools the role can use. See [Assign Agent UI tools](#assign-agent-ui-tools)
  * <mark style="color:blue;">Assign Skills</mark>: Assign the skills the role can read, with individual read/edit/delete permissions and an option to allow creating skills (see [Skill Management: Control Skill Visibility and Permissions by Role](https://docs.maiagent.ai/maiagent-user-guide/en/build/skills/skills-management.md#skill-role-visibility))
  * <mark style="color:blue;">Assign Conversation Platforms</mark>: Assign the conversation platforms the role can use
  * <mark style="color:blue;">Credit Quota</mark>: Available only for organizations billed in Credits. Set a quota shared by the entire role (see [Role Quotas](https://docs.maiagent.ai/maiagent-user-guide/en/others/credits/member-credit-quota.md#role-quota))
* <mark style="color:blue;">Delete</mark>: Remove unused roles to keep the organization's permission structure organized. The default role cannot be deleted
* <mark style="color:blue;">Bulk Permission Settings</mark>: Apply the same permission settings to multiple custom roles at once. Preview what will be added or revoked for each role before applying them (see [Bulk Role Permission Settings](https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/role-batch-permissions.md))
* <mark style="color:blue;">Bulk Actions</mark>: Use Excel to add members to the organization or assign roles to members in bulk (see [Member Management: Bulk Member and Permission Management](https://docs.maiagent.ai/maiagent-user-guide/en/org/overview/member.md#batch-member-permission-management))

{% hint style="info" %}
**Role settings tabs**

* **Owner role**: Resource assignment tabs, including Assign MaiGPT Permissions, Assign AI Assistants, Assign Teams, Assign Knowledge Bases, Assign Databases, Assign Tools, Assign Agent UI Tools, Assign Skills, and Assign Conversation Platforms, are disabled because owners automatically have access to all resources
* **Default role**: The Assign Members tab is disabled because the default role is automatically assigned to all members
  {% endhint %}

### Duplicate a Role <a href="#duplicate-role" id="duplicate-role"></a>

When creating a role with settings similar to an existing role, you do not need to select all permissions from scratch:

1. Find the source role in the role list and click the <mark style="color:blue;">Duplicate</mark> icon in the actions column (only custom roles have this icon; owner and default roles cannot be duplicated)
2. In the <mark style="color:blue;">Duplicate Role</mark> dialog, confirm the <mark style="color:blue;">Source Role</mark> and change the <mark style="color:blue;">New Role Name</mark> (the default is “Source role name - Copy”)
3. Click <mark style="color:blue;">Confirm Duplication</mark>. The new role appears in the list. Click <mark style="color:blue;">Edit</mark> to adjust its settings

{% hint style="warning" %}
The new role inherits the source role's permissions and resource bindings, including each resource's read/edit/delete settings. Members and quotas are not copied; configure them separately for the new role if needed.

To apply the same permissions to multiple existing roles, use [Bulk Permission Settings](https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/role-batch-permissions.md).
{% endhint %}

***

## Permission Hierarchy <a href="#permission-levels" id="permission-levels"></a>

MaiAgent uses a **hierarchical permission structure**, with **parent permissions** and **child permissions**:

{% hint style="info" %}
**What is a hierarchical permission structure?**

Think of a folder structure:

* **Parent permission** = Parent folder (for example, “AI Features”)
* **Child permission** = Subfolder (for example, “AI Assistants,” “Knowledge Bases,” or “Crawlers”)

**How it works:**

* Selecting a parent permission automatically includes all its child permissions
* You can also select only specific child permissions for finer control
  {% endhint %}

### Permission Structure Overview <a href="#permission-structure-overview" id="permission-structure-overview"></a>

The table below lists permissions for currently available features (14 parent permissions and 41 child permissions). A dash (—) indicates a parent permission with no children. Each description identifies the page or operation controlled by that permission; follow the links for feature instructions.

| Parent Permission                             | Child Permission                            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| --------------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **MaiGPT Permissions**                        | —                                           | Controls whether [MaiGPT](https://docs.maiagent.ai/maiagent-user-guide/en/work/maigpt.md) appears in the left menu and can be used                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| **Agent Marketplace Permissions**             | View Inactive Official Agents               | Parent permission: controls whether <mark style="color:blue;">Agent Marketplace</mark> appears in the left menu and can be used ([Chat with Agents](https://docs.maiagent.ai/maiagent-user-guide/en/work/explain.md)). Child permission: controls whether the <mark style="color:blue;">Official Built-in</mark> tab in <mark style="color:blue;">Agent Marketplace</mark> lists official Agents the organization has not activated. Without it, only activated Agents are visible ([Who Can See Inactive Official Agents](https://docs.maiagent.ai/maiagent-user-guide/en/work/built-in-agents/use.md#inactive-visibility)) |
| **Meeting Records Permissions**               | Live Transcription Permissions              | Allows creating a new meeting and starting recording in [Meeting Records](https://docs.maiagent.ai/maiagent-user-guide/en/work/meeting-records.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
|                                               | Meeting List Permissions                    | Allows viewing the meeting list and details, and downloading recordings                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| **Meeting Records Management Permissions**    | —                                           | When the organization enables meeting privacy mode, allows viewing all meetings in the organization, including those the member did not create or was not added to (see [Meeting Access Permissions](https://docs.maiagent.ai/maiagent-user-guide/en/work/meeting-records/access-control.md))                                                                                                                                                                                                                                                                                                                                |
| **File Library Permissions**                  | Personal Space Permissions                  | Displays [File Library](https://docs.maiagent.ai/maiagent-user-guide/en/work/file-library.md) in the left menu and allows using one's own <mark style="color:blue;">My Files</mark>                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|                                               | Organization Space View Permissions         | Allows browsing, searching, and downloading <mark style="color:blue;">Organization Shared Files</mark>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
|                                               | Organization Space Edit Permissions         | Allows uploading, moving, renaming, and deleting files in Organization Shared Files                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|                                               | Create Shared Spaces Permissions            | Allows creating and deleting [Shared Spaces](https://docs.maiagent.ai/maiagent-user-guide/en/work/file-library/shared-spaces.md), and changing space names and authorized roles                                                                                                                                                                                                                                                                                                                                                                                                                                              |
|                                               | Permission to Be Invited to Shared Spaces   | Members can see a shared space only when their role is authorized for it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| **AI Features Permissions**                   | AI Assistant Permissions                    | The <mark style="color:blue;">AI Features</mark> → <mark style="color:blue;">AI Assistants</mark> page ([Agents](https://docs.maiagent.ai/maiagent-user-guide/en/build/agent.md)), and browsing and applying templates from the [Agent Template Library](https://docs.maiagent.ai/maiagent-user-guide/en/build/agent/agent-templates.md) (the organization plan must also include Agent Builder)                                                                                                                                                                                                                             |
|                                               | Knowledge Base Permissions                  | The <mark style="color:blue;">Knowledge Bases</mark> page ([Knowledge Bases](https://docs.maiagent.ai/maiagent-user-guide/en/build/knowledge-base.md))                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
|                                               | Tool Permissions                            | The <mark style="color:blue;">Tools</mark> page, including MCP connector management ([Tools](https://docs.maiagent.ai/maiagent-user-guide/en/build/tools.md))                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
|                                               | Crawler Permissions                         | The <mark style="color:blue;">Crawlers</mark> page ([Crawlers](https://docs.maiagent.ai/maiagent-user-guide/en/build/knowledge-base/crawler.md))                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
|                                               | Database Permissions                        | The <mark style="color:blue;">Databases</mark> page ([Databases](https://docs.maiagent.ai/maiagent-user-guide/en/build/database.md))                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
|                                               | Skill Permissions                           | The <mark style="color:blue;">Skills</mark> page ([Skills](https://docs.maiagent.ai/maiagent-user-guide/en/build/skills.md))                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
|                                               | Schedule Management Permissions             | The <mark style="color:blue;">Agent Schedules</mark> page: view, create, edit, enable/pause, run immediately, and delete schedules ([Agent Schedules](https://docs.maiagent.ai/maiagent-user-guide/en/build/agent/schedule.md))                                                                                                                                                                                                                                                                                                                                                                                              |
|                                               | Agent UI Permissions                        | The <mark style="color:blue;">Agent UI</mark> page ([Agent UI](https://docs.maiagent.ai/maiagent-user-guide/en/build/tools/agent-ui.md))                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
|                                               | Team Permissions                            | The <mark style="color:blue;">Teams</mark> page ([Agent Teams](https://docs.maiagent.ai/maiagent-user-guide/en/build/teams.md))                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
|                                               | Schedule View Permissions                   | Allows viewing the <mark style="color:blue;">Agent Schedules</mark> page, schedule details, quotas, and execution history, without making changes. <mark style="color:blue;">Schedule Management Permissions</mark> already includes this permission                                                                                                                                                                                                                                                                                                                                                                         |
| **Hook Permissions**                          | —                                           | The <mark style="color:blue;">Hook</mark> page: Hook templates, Hooks, and settings for attaching them to Agents ([Hook Message Interception](https://docs.maiagent.ai/maiagent-user-guide/en/build/hook.md))                                                                                                                                                                                                                                                                                                                                                                                                                |
| **AgentOps Permissions**                      | Test Dataset Permissions                    | The <mark style="color:blue;">AgentOps</mark> → <mark style="color:blue;">Test Datasets</mark> page ([Test Dataset Management](https://docs.maiagent.ai/maiagent-user-guide/en/build/agent-ops/test-datasets.md))                                                                                                                                                                                                                                                                                                                                                                                                            |
|                                               | Automated Testing Permissions               | The <mark style="color:blue;">Automated Testing</mark> page ([Automated Evaluation and Agent Monitoring](https://docs.maiagent.ai/maiagent-user-guide/en/build/agent-ops/evaluations.md))                                                                                                                                                                                                                                                                                                                                                                                                                                    |
|                                               | AI Assistant Monitoring Permissions         | The <mark style="color:blue;">AI Assistant Monitoring</mark> page ([Automated Evaluation and Agent Monitoring](https://docs.maiagent.ai/maiagent-user-guide/en/build/agent-ops/evaluations.md))                                                                                                                                                                                                                                                                                                                                                                                                                              |
|                                               | Tool Execution Records Permissions          | The <mark style="color:blue;">Tool Execution Records</mark> page ([Tool Execution Records](https://docs.maiagent.ai/maiagent-user-guide/en/build/agent-ops/tool-execution-records.md))                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| **Customer Service Conversation Permissions** | All Conversations Permissions               | The <mark style="color:blue;">Customer Service Conversations</mark> → <mark style="color:blue;">All Conversations</mark> page ([All Conversations](https://docs.maiagent.ai/maiagent-user-guide/en/serve/daily-operations/reply.md))                                                                                                                                                                                                                                                                                                                                                                                         |
|                                               | Transfer Others' Conversations Permissions  | Allows transferring conversations handled by other customer service agents. Without it, members can transfer only conversations they handle themselves ([Transfer Others' Conversations Permissions](https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/transfer-others-permission.md))                                                                                                                                                                                                                                                                                                                               |
|                                               | Conversation Platform Permissions           | The <mark style="color:blue;">Conversation Platforms</mark> page ([Conversation Platform Settings Overview](https://docs.maiagent.ai/maiagent-user-guide/en/build/conversation-settings/platform-settings.md)), and <mark style="color:blue;">Platform Settings</mark> and <mark style="color:blue;">Connect Channels</mark> in an Agent's <mark style="color:blue;">Conversation Platforms</mark> tab (see [Without conversation platform permissions](#without-inbox-permission))                                                                                                                                          |
|                                               | Contact Permissions                         | The <mark style="color:blue;">Contacts</mark> page ([Contacts](https://docs.maiagent.ai/maiagent-user-guide/en/serve/daily-operations/contact.md))                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
|                                               | Conversation Platform Analytics Permissions | The <mark style="color:blue;">Conversation Platform Analytics</mark> page ([Conversation Platform Analytics](https://docs.maiagent.ai/maiagent-user-guide/en/serve/daily-operations/reply/inbox-analysis.md))                                                                                                                                                                                                                                                                                                                                                                                                                |
| **Call Center Permissions**                   | Call Console                                | The <mark style="color:blue;">Call Center</mark> → <mark style="color:blue;">Call Console</mark> page ([Phone Customer Service (Call Center)](https://docs.maiagent.ai/maiagent-user-guide/en/build/choose-channel/call-center.md))                                                                                                                                                                                                                                                                                                                                                                                          |
|                                               | Call History                                | The <mark style="color:blue;">Call History</mark> page                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
|                                               | Incoming Call Settings                      | The <mark style="color:blue;">Incoming Call Settings</mark> page                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| **AI Gateway Permissions**                    | —                                           | Controls whether [AI Gateway](https://docs.maiagent.ai/maiagent-user-guide/en/build/ai-gateway.md) appears in the left menu and can be accessed. The system also rejects AI Gateway API requests from members without this permission                                                                                                                                                                                                                                                                                                                                                                                        |
| **Organization Settings Permissions**         | Organization Overview Permissions           | The <mark style="color:blue;">Organization Settings</mark> → <mark style="color:blue;">Organization Overview</mark> page, including its <mark style="color:blue;">Management Actions</mark> (entries for editing members, editing role permissions, identity synchronization, OAuth applications, and more; [Organization Overview](https://docs.maiagent.ai/maiagent-user-guide/en/org/overview/organization-overview.md))                                                                                                                                                                                                  |
|                                               | Activity Log Permissions                    | The <mark style="color:blue;">Activity Log</mark> page ([Activity Log](https://docs.maiagent.ai/maiagent-user-guide/en/org/activity-log.md))                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
|                                               | Usage Statistics Permissions                | The <mark style="color:blue;">Usage Statistics</mark> page ([Usage Statistics](https://docs.maiagent.ai/maiagent-user-guide/en/others/usage-statistics.md)). After selecting it, set the <mark style="color:blue;">Usage Statistics Scope</mark> to <mark style="color:blue;">Entire Organization</mark> (default) or <mark style="color:blue;">Authorized Assistants Only</mark> (see [View Usage for Authorized Agents Only](https://docs.maiagent.ai/maiagent-user-guide/en/others/usage-statistics.md#scope-to-authorized-agents))                                                                                       |
|                                               | Credit Management Permissions               | The <mark style="color:blue;">Credits</mark> page ([Credits Billing System](https://docs.maiagent.ai/maiagent-user-guide/en/others/credits.md#management-panel))                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
|                                               | Billing Management Permissions              | The <mark style="color:blue;">Billing Management</mark> page, including Credit settings and payment information                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
|                                               | Model Access Permissions                    | The <mark style="color:blue;">Model Access Permissions</mark> page ([Model Access Permissions](https://docs.maiagent.ai/maiagent-user-guide/en/org/model-access.md))                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
|                                               | Identity Sync Permissions                   | Allows managing <mark style="color:blue;">Identity Sync</mark> settings ([Identity Sync (LDAP/SCIM)](https://docs.maiagent.ai/maiagent-user-guide/en/org/identity-sync.md))                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
|                                               | API Key Management Permissions              | The <mark style="color:blue;">API Key Management</mark> page ([API Key Management](https://docs.maiagent.ai/maiagent-user-guide/en/org/developer/api-keys.md))                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
|                                               | OAuth Application Management Permissions    | Allows creating, editing, and deleting <mark style="color:blue;">OAuth Applications</mark> and regenerating client secrets. Viewing the list does not require this permission ([OAuth Applications](https://docs.maiagent.ai/maiagent-user-guide/en/org/developer/oauth-applications.md))                                                                                                                                                                                                                                                                                                                                    |
|                                               | Built-in Agent Management Permissions       | The <mark style="color:blue;">Built-in Agent Management</mark> page: activate/deactivate official built-in Agents ([Official Built-in Agent Management](https://docs.maiagent.ai/maiagent-user-guide/en/org/management.md))                                                                                                                                                                                                                                                                                                                                                                                                  |
| **Developer Permissions**                     | API Call Log Permissions                    | The <mark style="color:blue;">Developer</mark> → <mark style="color:blue;">API Call Logs</mark> page ([API Call Logs](https://docs.maiagent.ai/maiagent-user-guide/en/org/developer/api-logs.md))                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **MaiGPT Connector Management Permissions**   | —                                           | Allows adding and enabling/disabling the organization's MaiGPT connectors from the MCP Registry ([Manage Connectors (Administrators)](https://docs.maiagent.ai/maiagent-user-guide/en/work/maigpt/connectors/connectors-admin.md)). Members only need MaiGPT permissions to use connectors                                                                                                                                                                                                                                                                                                                                   |

{% hint style="info" %}
**Permission hierarchy explained**

* Selecting a parent permission automatically includes all its child permissions
* You can also select only specific child permissions for finer permission control
* A user's final permissions are the sum of the system's default role and custom role permissions
* <mark style="color:blue;">View Inactive Official Agents</mark> is not inherited from the parent permission: selecting <mark style="color:blue;">Agent Marketplace Permissions</mark> selects this checkbox by default, but once cleared, only this checkbox's setting applies. To hide inactive official Agents from a member, clear it in both the default role and all roles assigned to that member. See [Who Can See Inactive Official Agents](https://docs.maiagent.ai/maiagent-user-guide/en/work/built-in-agents/use.md#inactive-visibility)
* Permissions shown in the interface but not listed in this table belong to features that are not yet officially available
* General feature permissions determine which feature pages are visible; <mark style="color:blue;">Transfer Others' Conversations Permissions</mark> controls an action within conversations. See [Transfer Others' Conversations Permissions](https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/transfer-others-permission.md) for setup. The Agents, knowledge bases, and conversation platforms a member can actually operate are determined separately by [Member and resource assignments](#assign-members) and [Role Resource Access Permissions](https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/group-resource-access.md)
  {% endhint %}

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-216a34d862464be493f54dcdd28e66c38768a1f1%2Frole-permission-view-inactive-official-agents.png?alt=media" alt="Agent Marketplace Permissions on the role permissions page, with the child permission View Inactive Official Agents, which controls whether official Agents not yet activated by the organization appear in the Official Built-in tab of Agent Marketplace"><figcaption><p>View Inactive Official Agents under Agent Marketplace Permissions</p></figcaption></figure>

### Permission Settings <a href="#permission-settings" id="permission-settings"></a>

1. Add a role and assign permissions

Click <mark style="color:blue;">Add Role</mark> in the upper right, enter the new role's name, and select its permissions.

2. Edit the name and permissions

Open the edit page, change the role's name, and select its permissions again.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-470041daafa472fd4ed71bcaf1937aed0f200480%2Fimage%20(222).png?alt=media" alt="The role permissions page lets you set the role name and select feature permissions"><figcaption></figcaption></figure>

Based on the role's purpose, decide whether organization members can see or use the relevant feature tabs in the left menu. Use the checkboxes to enable or disable each permission, then click <mark style="color:blue;">Save</mark> in the lower right to apply the settings.

### Allow Specific Roles to Use AI Gateway <a href="#enable-ai-gateway-for-role" id="enable-ai-gateway-for-role"></a>

If only model administrators in your company need to view AI Gateway, enable this permission only for their roles:

1. Go to <mark style="color:blue;">Organization Settings</mark> → <mark style="color:blue;">Organization Overview</mark>, then click <mark style="color:blue;">Edit Role Permissions</mark> under <mark style="color:blue;">Management Actions</mark>.
2. To create a role, click <mark style="color:blue;">Add Role</mark> and enter a role name. You can also edit an existing role's <mark style="color:blue;">Role Permissions</mark> directly.
3. Select <mark style="color:blue;">AI Gateway Permission</mark>, then click <mark style="color:blue;">Confirm</mark>. In the English interface, the button is labeled <mark style="color:blue;">OK</mark>.
4. Assign model administrators to this role. When members reenter the admin console, AI Gateway appears in the left menu. Members without this permission cannot see the menu or access the related pages directly, and the system rejects their AI Gateway API requests.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-87a186a534fe69fc7247cfb7c71bdd9067dff353%2Fai-gateway-role-permission.png?alt=media" alt="AI Gateway Permission selected in the role permissions dialog"><figcaption><p>Select AI Gateway Permission so members of this role can see and access AI Gateway</p></figcaption></figure>

{% 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 roles as well.
{% endhint %}

***

## Permission Use Cases <a href="#permission-use-cases" id="permission-use-cases"></a>

Suppose a company uses MaiAgent to build a customer service system:

### Scenario 1: New Customer Service Agent <a href="#use-case-new-agent" id="use-case-new-agent"></a>

Grant only **Agent Marketplace Permissions**

* **Reason**: The new employee needs to learn product knowledge and company policies quickly
* **Problem to avoid**: Prevent the agent from accidentally deleting customer conversation records or changing important Agent settings before becoming familiar with the system

### Scenario 2: Senior Customer Service Agent <a href="#use-case-senior-agent" id="use-case-senior-agent"></a>

Agent Marketplace Permissions + Customer Service Conversation Permissions (All Conversations)

* **Reason**: Experienced staff need to help handle complex complaints and guide new employees
* **Problem to avoid**: Continue withholding AI Features permissions to prevent staff from accidentally changing Agent settings and causing incorrect replies to all customers

### Scenario 3: Agent Administrator <a href="#use-case-ai-admin" id="use-case-ai-admin"></a>

AI Features Permissions + AgentOps Permissions

* **Reason**: Responsible for managing and improving Agent response quality
* **Problem to avoid**: Withhold Customer Service Conversation permissions to prevent access to customers' private data

***

## Assign Members <a href="#assign-members" id="assign-members"></a>

Assign the roles you have created to members of your organization:

1. Click <mark style="color:blue;">Edit</mark> for the role in the role list, then switch to the <mark style="color:blue;">Assign Members</mark> tab
2. Click the <mark style="color:blue;">Assign Members</mark> button
3. Select the members to add on the left side of the dialog, then click <mark style="color:blue;">Add ></mark> in the center to move them to the right
4. Click <mark style="color:blue;">Confirm</mark> in the lower right to finish

The members you just added appear in the member list.

After being added, if a member has only the <mark style="color:blue;">AI Assistant</mark> permission, the left menu displays only Agent features. Customer service conversations, organization settings, and other features do not appear in the menu. If the member opens a feature without permission by entering its URL directly, a page explains that they do not have access. This limits the member to using Agent features and prevents other changes.

{% hint style="info" %}
Need to assign roles to multiple members at once? See [Member Management: Batch Member and Permission Management](https://docs.maiagent.ai/maiagent-user-guide/en/org/overview/member.md#batch-member-permission-management).
{% endhint %}

***

## <mark style="color:blue;">Assign AI Assistants</mark> <a href="#assign-chatbots" id="assign-chatbots"></a>

You can limit which Agents a role can use to keep knowledge base data accessible according to role permissions:

1. Open the "<mark style="color:blue;">Assign AI Assistants</mark>" page
2. Click the "<mark style="color:blue;">Assign AI Assistants</mark>" button
3. Select the Agents to add under "Available AI Assistants" on the left, then click the "<mark style="color:blue;">Add AI Assistants ></mark>" button in the center to move them to "Selected AI Assistants" on the right
4. Click the "<mark style="color:blue;">Confirm</mark>" button in the lower-right corner to finish

The selected Agents appear in the list. You can select Read, Edit, and Delete separately for each row. Users with this role can only view and use the assigned Agents.

To revoke an Agent, move it from the assigned list on the right back to the left in the same dialog. The Agent's conversation platforms are also revoked from this role. See [Select All and Remove Items in Assignment Dialogs](#assign-picker-select-remove).

{% hint style="info" %}
The owner role automatically has access to all Agents and does not require manual assignment.
{% endhint %}

***

## Assign Teams <a href="#assign-teams" id="assign-teams"></a>

Administrators can use roles to manage [Agent Teams](https://docs.maiagent.ai/maiagent-user-guide/en/build/teams.md) permissions centrally, giving members access to the teams they need for work and allowing them to view records or change settings according to their responsibilities.

For example, a customer service supervisor wants colleagues to use the customer service team, while only maintainers can edit its canvas. She assigns the team to the customer service role with <mark style="color:blue;">Use</mark> enabled, then assigns the same team to the maintenance role with <mark style="color:blue;">Edit</mark> selected. The two roles share the same team while handling conversations and maintenance separately.

{% stepper %}
{% step %}
Edit the target role in the role list, switch to <mark style="color:blue;">Assign Teams</mark>, and click the button with the same name.
{% endstep %}

{% step %}
Select teams on the left, click <mark style="color:blue;">Add Teams ></mark> to move them to the right, then click <mark style="color:blue;">Confirm</mark>.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-fddb445fbc27630d5fae88e377c8fc4b38b4443c%2Fteam-role-assignment-prod.png?alt=media" alt="Filter and selection status for selected teams: a fictional demo customer service team, with one item in total and one selected"><figcaption><p>Filter and selection status in the selected teams list on the right</p></figcaption></figure>
{% endstep %}

{% step %}
Newly assigned teams have only <mark style="color:blue;">Use</mark> enabled by default. Return to the list and select any other permissions you need. Selections are saved immediately; no separate Save button is required.

| Permission                | What members can do                                                                                                                       |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Use                       | Use the team's conversation platform and open the team page if they also have the team feature permission.                                |
| View Conversation History | View the team's conversation and execution records. Members without this permission can still view conversations they started themselves. |
| Edit                      | Modify the team's canvas, member nodes, and entry settings.                                                                               |
| Delete                    | Delete the entire team. Deleting nodes or connections on the canvas is covered by Edit.                                                   |

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-928d3aa4d3e6b0fd28329870f546cadf270228b7%2Fteam-role-permissions-prod.png?alt=media" alt="Assign Teams list: Use, View Conversation History, Edit, and Delete are all selected for the demo customer service team"><figcaption><p>The four permissions for the same team can be granted separately by role</p></figcaption></figure>
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Selecting "View Conversation History," "Edit," or "Delete" also enables "Use." Clearing "Use" disables the other three permissions. If a member has multiple roles, team permissions are the union of those roles. Owners do not need individual assignments.
{% endhint %}

To let role members create teams, select <mark style="color:blue;">Allow Creating Teams</mark>. Members still need the team feature permission and a plan that supports Agent Builder. A new team is authorized for the creator's custom roles, so other members with the same roles also receive full permissions for that team. If the creator has no custom role, ask an administrator to assign access separately.

For newly created roles, <mark style="color:blue;">Allow Creating Teams</mark> is cleared by default, as it is for the default role in a new organization. Existing roles keep their current settings. When a role is copied, the new role inherits the source role's checkbox setting. A member can create teams if any of their roles has this option selected. To restrict team creation, make sure the option is cleared in both the default role and all other roles assigned to the member.

For example, an administrator creates a "Marketing Planning" role and lets its members use teams, but does not yet want them to create their own. After creating the role, the administrator switches to <mark style="color:blue;">Assign Teams</mark>. <mark style="color:blue;">Allow Creating Teams</mark> is already cleared, so no additional action is needed. The administrator can return and select it later when team creation is needed.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-ce8e3c9d693ac72eee3620ce2412c9117d28c7c4%2Frole-permission-new-role-team-create-off.png?alt=media" alt="Assign Teams tab for a newly created role: Allow Creating Teams is cleared, and the list below shows that no teams have been assigned to this role"><figcaption><p>Allow Creating Teams is cleared by default for newly created roles</p></figcaption></figure>

A team's entry assistant and conversation platforms follow the team's permissions. You do not need to configure them individually under "Assign AI Assistants" or "Assign Conversation Platforms." The latter displays read-only rows for team platforms after regular platforms, labeled <mark style="color:blue;">Authorized by team: Team name</mark>. As with regular platforms, the <mark style="color:blue;">Channel Type</mark> column shows types such as Web, Internal, and API. To make changes, click <mark style="color:blue;">Go to Assign Teams</mark>.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-64ecdcda615d594e4f7350392dafdb75ce13dc62%2Frole-permission-team-inbox-access-types.png?alt=media" alt="Assign Conversation Platforms tab: the fictional demo customer service team&#x27;s three conversation platforms are labeled as authorized by the team, with Web, Internal, and API channel types"><figcaption><p>Read-only rows for team platforms show their actual types: Web, Internal, and API</p></figcaption></figure>

***

## Assign Knowledge Bases <a href="#assign-knowledge-bases" id="assign-knowledge-bases"></a>

You can limit which knowledge bases a role can access to ensure that only specific roles have access to sensitive data:

1. Open the "<mark style="color:blue;">Assign Knowledge Bases</mark>" page
2. Click the "<mark style="color:blue;">Assign Knowledge Bases</mark>" button

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-a44e2516b06f0770bbb7b088f247663c32fa0556%2F%E6%88%AA%E5%9C%96%202025-12-10%20%E4%B8%8B%E5%8D%883.28.14.png?alt=media" alt="Assign Knowledge Bases dialog, with available knowledge bases on the left and selected knowledge bases on the right"><figcaption></figcaption></figure>

3. Select the knowledge bases to add, then click the "<mark style="color:blue;">Add Knowledge Bases ></mark>" button in the center
4. Click the "<mark style="color:blue;">Confirm</mark>" button in the lower-right corner to finish

The selected knowledge bases appear in the list. To select knowledge bases across multiple pages at once or remove assigned knowledge bases within the dialog, see [Select All and Remove Items in Assignment Dialogs](#assign-picker-select-remove).

**Use cases:**

* **R\&D department**: Access only the technical documentation knowledge base
* **Sales department**: Access only the product information and quotation knowledge base
* **HR department**: Access only the employee handbook knowledge base

{% hint style="info" %}
The owner role automatically has access to all knowledge bases and does not require manual assignment.
{% endhint %}

***

## Assign Conversation Platforms <a href="#assign-inboxes" id="assign-inboxes"></a>

You can limit which conversation platforms a role can use so that different teams handle different customer service channels:

1. Open the "<mark style="color:blue;">Assign Conversation Platforms</mark>" page
2. Click the "<mark style="color:blue;">Assign Conversation Platforms</mark>" button

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-ceca88e9a787a75b3815c78ad5a4b1bd656451d4%2F%E6%88%AA%E5%9C%96%202025-12-10%20%E4%B8%8B%E5%8D%883.28.49.png?alt=media" alt="Assign Conversation Platforms dialog, where you can filter by AI assistant and channel type and view selected platforms"><figcaption></figcaption></figure>

3. Select the conversation platforms to add, then click the "<mark style="color:blue;">Add Conversation Platforms ></mark>" button in the center
4. Click the "<mark style="color:blue;">Confirm</mark>" button in the lower-right corner to finish

The selected conversation platforms appear in the list. <mark style="color:blue;">Select All</mark> on the left selects items across all pages. To replace a set of assigned conversation platforms, you can remove the old ones and add new ones in the same dialog. See [Select All and Remove Items in Assignment Dialogs](#assign-picker-select-remove).

**Use cases:**

* **LINE customer service team**: Access only LINE conversation platforms
* **Website customer service team**: Access only Web Chat conversation platforms
* **VIP customer service team**: Access all conversation platforms

{% hint style="info" %}
The owner role automatically has access to all conversation platforms and does not require manual assignment.
{% endhint %}

***

## Assign Databases, Tools, and Agent UI Tools <a href="#assign-databases-tools" id="assign-databases-tools"></a>

These three tabs share the same layout; only the type of resource being assigned differs. Each tab contains the following, from top to bottom:

* **Search bar**: Enter a name or ID to filter assigned items. The <mark style="color:blue;">Assign ○○</mark> button on the right opens the assignment dialog. As with assigning AI assistants, select items on the left, add them to the right, and click <mark style="color:blue;">Confirm</mark>
* **Allow Creating ○○** checkbox: When selected, members with this role can create new databases, tools, or Agent UI tools on the corresponding page. When cleared, they can only use assigned items. This is a creation permission, separate from access permissions for each resource below. See [Organization and Member Management: What a Role Contains](https://docs.maiagent.ai/maiagent-user-guide/en/org/overview.md#what-a-role-holds)
* **Assigned list**: Each row has separate <mark style="color:blue;">Read</mark>, <mark style="color:blue;">Edit</mark>, and <mark style="color:blue;">Delete</mark> checkboxes that take effect immediately. The header checkbox toggles all rows on the current page at once. The delete icon on the far right removes the resource from this role without deleting the resource itself

For details about the Read, Edit, and Delete switches, see [Role Resource Access Permissions](https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/group-resource-access.md) and [Role Resource Visibility Control](https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/group-resource-visibility.md).

### Assign Databases <a href="#assign-databases" id="assign-databases"></a>

Choose which [databases](https://docs.maiagent.ai/maiagent-user-guide/en/build/database.md) this role can see and whether it can create new databases (<mark style="color:blue;">Allow Creating Databases</mark>). You can also configure the same setting from a database by adding the role to its group permissions. Both sides display the same association. See [Linking Agents and Group Permissions: Group Permission Management](https://docs.maiagent.ai/maiagent-user-guide/en/build/database/link-chatbots-groups.md#group-permission-management).

### Assign Tools <a href="#assign-tools" id="assign-tools"></a>

Choose which tools this role can see on the [Tools](https://docs.maiagent.ai/maiagent-user-guide/en/build/tools.md) page and attach to Agents, and whether it can create new tools (<mark style="color:blue;">Allow Creating Tools</mark>). Members also need <mark style="color:blue;">Tool Permissions</mark> under <mark style="color:blue;">AI Feature Permissions</mark> to see the Tools page. Members need both permissions to use tools.

### Assign Agent UI Tools <a href="#assign-agent-ui-tools" id="assign-agent-ui-tools"></a>

Choose which [Agent UI](https://docs.maiagent.ai/maiagent-user-guide/en/build/tools/agent-ui.md) tools this role can use and whether it can create new Agent UI tools (<mark style="color:blue;">Allow Creating Agent UI Tools</mark>). The list includes an additional <mark style="color:blue;">Tool Type</mark> column to help identify each tool's type. Members also need <mark style="color:blue;">Agent UI Permissions</mark> under <mark style="color:blue;">AI Feature Permissions</mark> to see the Agent UI page.

{% hint style="info" %}
The owner role automatically has access to all databases, tools, and Agent UI tools. These three tabs are disabled for the owner role.
{% endhint %}

***

## Filter and Hide Official Built-in Assistants in Assignment Dialogs <a href="#assign-picker-filters" id="assign-picker-filters"></a>

When an organization enables an official built-in Agent, it automatically comes with three conversation platforms: Web, Internal, and API. These appear in the same candidate list as custom Agents and conversation platforms. Both the <mark style="color:blue;">Assign AI Assistants</mark> and <mark style="color:blue;">Assign Conversation Platforms</mark> dialogs have a <mark style="color:blue;">Filter</mark> bar at the top, allowing you to narrow down the candidate list on the left before selecting items.

**Use case:**

An organization administrator wants to assign all conversation platforms for the "Customer Feedback Analysis" Agent to the "Customer Service Department" role. However, the candidate list contains hundreds of platforms, many of which were automatically created for official built-in Agents. In the <mark style="color:blue;">Assign Conversation Platforms</mark> dialog, the administrator selects <mark style="color:blue;">Hide Official Built-in Assistants</mark>, then chooses "Customer Feedback Analysis" from the <mark style="color:blue;">All AI Assistants</mark> dropdown. Only this Agent's Web, Internal, and API platforms remain on the left. The administrator clicks <mark style="color:blue;">Select All</mark>, <mark style="color:blue;">Add Conversation Platforms ></mark>, and then <mark style="color:blue;">Confirm</mark>, without having to check platform names page by page.

### Assign Conversation Platforms: Filter by Agent and Channel Type <a href="#filter-inbox-picker" id="filter-inbox-picker"></a>

Go to <mark style="color:blue;">Organization Settings</mark> → <mark style="color:blue;">Organization Overview</mark> → <mark style="color:blue;">Management Actions</mark> → <mark style="color:blue;">Edit Role Permissions</mark> → Edit Role → the <mark style="color:blue;">Assign Conversation Platforms</mark> tab, and click the <mark style="color:blue;">Assign Conversation Platforms</mark> button to open the dialog. The <mark style="color:blue;">Filter</mark> bar at the top has three conditions:

| Filter                                                             | Effect                                                                                                                                                                                                                 |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">All AI Assistants</mark>                 | Select an Agent to list only the conversation platforms linked to it on the left. You can search by name in the dropdown                                                                                               |
| <mark style="color:blue;">All Channel Types</mark>                 | List only conversation platforms of the specified channel type, such as Web, LINE, or Messenger                                                                                                                        |
| <mark style="color:blue;">Hide Official Built-in Assistants</mark> | When selected, all conversation platforms for official built-in Agents are hidden from the left list. The <mark style="color:blue;">All AI Assistants</mark> dropdown also lists only the organization's custom Agents |

* All three conditions and <mark style="color:blue;">Search Available Conversation Platforms</mark> on the left apply together. Changing any condition resets the list to page 1.
* Filters affect only <mark style="color:blue;">Available Conversation Platforms</mark> on the left. <mark style="color:blue;">Selected Conversation Platforms</mark> on the right still shows all items, regardless of the filters.
* If you select an official built-in Agent in <mark style="color:blue;">All AI Assistants</mark> and then select <mark style="color:blue;">Hide Official Built-in Assistants</mark>, the Agent selection is cleared automatically, and the list displays conversation platforms for all custom Agents.
* If no items match the filters, the list displays "No items match the filter criteria."

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-0dc12a30f1924d28832a51cb4042a53f9db3814b%2Frole-permission-assign-inbox-filter.png?alt=media" alt="Assign Conversation Platforms dialog: an Agent is selected in the filter bar and Hide Official Built-in Assistants is selected, leaving only that Agent&#x27;s three conversation platforms on the left"><figcaption><p>After selecting an Agent and hiding official built-in assistants, only that Agent's Web, Internal, and API platforms appear on the left</p></figcaption></figure>

### <mark style="color:blue;">Assign AI Assistants</mark>: <mark style="color:blue;">Hide Official Built-in Assistants</mark> <a href="#filter-chatbot-picker" id="filter-chatbot-picker"></a>

The candidates in the <mark style="color:blue;">Assign AI Assistants</mark> dialog are Agents themselves, so the filter bar contains only the <mark style="color:blue;">Hide Official Built-in Assistants</mark> checkbox:

* **Cleared**: Official built-in Agents appear alongside custom Agents, with an <mark style="color:blue;">Official Built-in</mark> label on the right for easy identification.
* **Selected**: <mark style="color:blue;">Available AI Assistants</mark> on the left lists only the organization's custom Agents, and the total count updates accordingly.

<div><figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-7df42f539b5867b12ae6aac2d1b7d7e0417f71bc%2Frole-permission-assign-chatbot-builtin-tag.png?alt=media" alt="Assign AI Assistants dialog: searching for Message Polishing with Hide Official Built-in Assistants cleared"><figcaption><p>Candidate list with Hide Official Built-in Assistants cleared; the search finds one custom assistant created by the organization</p></figcaption></figure> <figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-0062b0ac45b31c1b109b64dada6c5b19100bd1c3%2Frole-permission-assign-chatbot-hide-builtin.png?alt=media" alt="Assign AI Assistants dialog: after selecting Hide Official Built-in Assistants, search results still show the organization&#x27;s custom Message Polishing assistant"><figcaption><p>After selection, the organization's custom assistant remains in the candidate list</p></figcaption></figure></div>

{% hint style="info" %}
**Rules for hiding official built-in assistants**

* The option is cleared by default. Closing the dialog or switching roles resets the filters in both dialogs.
* Hiding only removes official built-in Agents from the candidate list. It does not remove items already assigned to the role or change any permissions.
* Permissions to use official built-in Agents are not configured on the role permissions page. Use the official built-in Agent's "Access Audience" settings instead. See [Official Built-in Agent Management: Set the Access Audience](https://docs.maiagent.ai/maiagent-user-guide/en/org/management.md#group-permissions).
  {% endhint %}

***

## Select All and Remove Items in Assignment Dialogs <a href="#assign-picker-select-remove" id="assign-picker-select-remove"></a>

The nine assignment dialogs on the role editing page—<mark style="color:blue;">Assign Members</mark>, <mark style="color:blue;">Assign AI Assistants</mark>, <mark style="color:blue;">Assign Teams</mark>, <mark style="color:blue;">Assign Knowledge Bases</mark>, <mark style="color:blue;">Assign Databases</mark>, <mark style="color:blue;">Assign Tools</mark>, <mark style="color:blue;">Assign Agent UI Tools</mark>, <mark style="color:blue;">Assign Skills</mark>, and <mark style="color:blue;">Assign Conversation Platforms</mark>—all have two columns. Available items are on the left, and items assigned to the role are on the right. You can add and remove items in the same dialog. Changes take effect only after you click <mark style="color:blue;">Confirm</mark>.

**Use case:**

An organization administrator wants to replace all 30 conversation platforms assigned to the "Customer Service Team 2" role with platforms for a newly launched Agent. On the role editing page, she opens <mark style="color:blue;">Assign Conversation Platforms</mark>, selects <mark style="color:blue;">Select All</mark> on the right, and clicks <mark style="color:blue;">< Remove Conversation Platforms</mark>. The 30 old platforms move back to the left and are marked <mark style="color:blue;">Will Be Removed</mark>. She then selects the new Agent from the <mark style="color:blue;">All AI Assistants</mark> dropdown at the top, selects <mark style="color:blue;">Select All</mark> on the left to select platforms across multiple pages, and clicks <mark style="color:blue;">Add Conversation Platforms ></mark>. The bottom of the dialog shows "30 items to add, 30 items to remove." She clicks <mark style="color:blue;">Confirm</mark>, checks the removal list in the confirmation dialog, and clicks <mark style="color:blue;">Confirm Removal</mark>, without deleting rows individually in the list.

### Select All Applies to All Pages <a href="#select-all-pages" id="select-all-pages"></a>

The list on the left is paginated. Selecting <mark style="color:blue;">Select All</mark> in the header selects **all items matching the current search text and filters**, including items on other pages. The right side of the header shows "N items selected."

* Items already assigned to this role are grayed out on the left and marked <mark style="color:blue;">Assigned</mark>. They cannot be selected and are excluded from Select All. Items added in the current session before clicking <mark style="color:blue;">Confirm</mark> are not marked. The <mark style="color:blue;">Assign Members</mark> dialog does not display this label.
* Items moved back to the left and marked <mark style="color:blue;">Will Be Removed</mark> are included in the selection. Adding them back to the right cancels their removal.
* <mark style="color:blue;">Select All</mark> on the right selects all items in the right list. If search text is entered, it selects only matching items.
* In the <mark style="color:blue;">Assign Members</mark> dialog, Select All is labeled <mark style="color:blue;">Select All Members</mark>, and the buttons are <mark style="color:blue;">Add ></mark> and <mark style="color:blue;">< Remove</mark>. They work the same way.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-3dd75823811aad2bb66ad0af08cdb9ac9a7a1d76%2Frole-permission-assign-assigned-tag.png?alt=media" alt="Assign Teams dialog: the fictional demo customer service team is grayed out and marked Assigned on the left, while the same team appears in Selected Teams on the right"><figcaption><p>Items already assigned to the role are marked Assigned on the left</p></figcaption></figure>

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-f72cbf7dd3e459f54b2487a8788f1a295c858100%2Frole-permission-assign-select-all.png?alt=media" alt="Assign Conversation Platforms dialog: the left list contains 85 items across 9 pages, and selecting Select All shows 85 items selected"><figcaption><p>Select All on the left selects items on all pages, including those outside the current page</p></figcaption></figure>

### Remove Assigned Items Within the Dialog <a href="#remove-in-picker" id="remove-in-picker"></a>

1. Open the assignment dialog. Items currently assigned to this role appear on the right.
2. Select the items to remove on the right, then click the <mark style="color:blue;">< Remove</mark> button in the center, such as <mark style="color:blue;">< Remove Conversation Platforms</mark>. The items move back to the left and are marked <mark style="color:blue;">Will Be Removed</mark>. If you change your mind, select them and move them back to the right to cancel the removal.
3. Items added in the current session are marked <mark style="color:blue;">New</mark> on the right. At the bottom of the dialog, "N items to add, N items to remove" appears to the left of <mark style="color:blue;">Confirm</mark>.
4. Click <mark style="color:blue;">Confirm</mark>. If items are being removed, a confirmation dialog first asks "Remove N ○○ from this role?" and lists each item to be removed. Conversation platforms include their channel types and associated AI assistants. Click <mark style="color:blue;">Confirm Removal</mark> to proceed. If you are only adding items, changes are saved directly without a confirmation dialog.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-05aa96882d9dc8ea7ea1d5718a8c708266cd8c9a%2Frole-permission-assign-pending-remove.png?alt=media" alt="Assign Conversation Platforms dialog: three conversation platforms on the left are marked Will Be Removed, three on the right are marked New, and the bottom shows 3 items to add and 3 items to remove"><figcaption><p>Items moved back to the left are marked Will Be Removed, and the bottom shows the number of changes in this session</p></figcaption></figure>

{% hint style="info" %}

* Removal only unlinks the role from the resource; it does not delete the resource itself. You can assign it again later, but permissions such as Read, Edit, and Delete will return to their defaults.
* Clicking <mark style="color:blue;">Cancel</mark> or closing the dialog discards all additions and removals made in this session.
  {% endhint %}

### Removing an AI Assistant Also Revokes Its Conversation Platforms <a href="#remove-chatbot-inboxes" id="remove-chatbot-inboxes"></a>

When you assign an AI assistant, the system also assigns its conversation platforms to the role. Removing the AI assistant revokes these platforms from the role as well, including settings adjusted under <mark style="color:blue;">Assign Conversation Platforms</mark>. The confirmation dialog lists the conversation platforms to be revoked under each assistant. After removal, switch to the <mark style="color:blue;">Assign Conversation Platforms</mark> tab; the list updates automatically.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-76ccbae6cf2efb9d985594e60e4dac5fe652983a%2Frole-permission-assign-chatbot-remove-confirm.png?alt=media" alt="Confirmation dialog: removing 1 AI assistant from this role, explaining that its conversation platforms will also be revoked, and listing the assistant&#x27;s three conversation platforms"><figcaption><p>Before removing an AI assistant, the confirmation dialog lists the conversation platforms that will also be revoked</p></figcaption></figure>

***

## Default Role <a href="#default-role-setting" id="default-role-setting"></a>

The default role is generated automatically when an organization is created and serves as the base role for all users. When applying a user's role settings, if no specific assignment is made, the system automatically applies all permission settings in the default role.

> Set the default role to the lowest permission level to prevent its permissions from overriding other role settings

***

## Permission Handling <a href="#permission-handling" id="permission-handling"></a>

When a user is assigned multiple roles, MaiAgent handles permissions as follows:

### Permission Union Principle (Union Principle) <a href="#permission-union-principle" id="permission-union-principle"></a>

**The system uses a "maximum permissions" strategy:** Users receive the union of permissions from all their roles, giving them the broadest set of allowed actions.

{% hint style="info" %}
**In simple terms:**

When a member belongs to multiple roles, they receive the union of permissions from all those roles, rather than the permissions of just one role.
{% endhint %}

**Example:**

```
Member B has the following roles:
├─ Customer Service role: Agent Marketplace permissions + All Conversations permissions
└─ Marketing role: AI Features permissions (AI Assistant) + All Conversations permissions

→ Member B's effective permissions: Agent Marketplace permissions + All Conversations permissions + AI Assistant permissions
   (Duplicate permissions are counted only once, not added repeatedly)
```

### Permission Application Order <a href="#permission-apply-order" id="permission-apply-order"></a>

The system calculates permissions in the following order:

```
Step 1: Apply the Default Role permissions
        ↓ (Automatic for all members)
Step 2: Apply Custom Role A permissions
        ↓ (Assigned by an administrator)
Step 3: Apply Custom Role B permissions
        ↓ (Assigned by an administrator)
Final permissions = Step 1 + Step 2 + Step 3
```

1. **Default role** (assigned automatically)
   * Generated automatically when the organization is created
   * Default role permissions are applied automatically to all users
2. **Custom roles** (in assignment order)
   * Roles assigned later are combined with existing permissions
   * They only add permissions; they do not override existing ones

{% hint style="warning" %}
**Key points:**

* Roles assigned later do not override existing permissions
* They only add more permissions
* Assigning a new role cannot reduce permissions

**To reduce someone's permissions, you must:**

1. Remove the member from the role, or
2. Modify the role's permission settings
   {% endhint %}

### Role Union Example <a href="#role-union-example" id="role-union-example"></a>

**Scenario:**

* The default role is associated with three Agents
* A custom role is associated with only two Agents

**Result:** Even when the user is assigned to the custom role, the settings associated with the default role are still included in the union, so the user can access three Agents.

{% hint style="info" %}
This is why we recommend keeping default role permissions to a minimum, so they do not affect permission control for other roles.
{% endhint %}

### Removing Permissions <a href="#permission-removal" id="permission-removal"></a>

When a user is removed from a role:

* **Removing a custom role**: The user loses permissions exclusive to that role and retains permissions from other roles
* **The 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: Agent Marketplace + AI Features + Customer Service Conversations
                ↓
Remove the "AI Feature Development" role
                ↓
Member A's effective permissions: Agent Marketplace + Customer Service Conversations
```

***

## What Members See Without Permission <a href="#what-members-see-without-permission" id="what-members-see-without-permission"></a>

When a role lacks permission for a feature, that feature is hidden from the left menu and certain list icons. If a member opens the page through a link, bookmark, or a link on another page, a permission denied message tells them to request access from the organization administrator.

### Hiding Entry Points Without Permission <a href="#hidden-entries" id="hidden-entries"></a>

The left menu only lists features the role has permission to use. Some icons in list action columns that lead to other feature pages are also shown or hidden based on permissions. For example, the analysis icon in the <mark style="color:blue;">Conversation Platforms</mark> list (with the tooltip "Conversation Platform Analysis") is hidden when the role lacks <mark style="color:blue;">Conversation Platform Analysis permissions</mark>. Only Edit and Delete remain in the action column, so members do not have to click the icon to discover they cannot access the page. Links on other pages may still appear; clicking them shows the permission denied screen below.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-6f522065555c8d28133dd8c0e4f33b3f7f1bede9%2Finbox-analysis-icon-by-permission.png?alt=media" alt="Comparison of the Conversation Platforms list action column: at the top, a role with Conversation Platform Analysis permissions sees Edit, Analysis, and Delete icons in each row; at the bottom, a role without this permission sees only Edit and Delete icons"><figcaption><p>For the same conversation platforms, roles without Conversation Platform Analysis permissions do not see the analysis icon</p></figcaption></figure>

### Without Conversation Platform Permissions <a href="#without-inbox-permission" id="without-inbox-permission"></a>

Conversation platform settings pages require <mark style="color:blue;">Conversation Platform permissions</mark> under <mark style="color:blue;">Customer Service Conversation permissions</mark>. When this permission is unchecked for a role, entry points to conversation platform settings are adjusted based on permissions, even if members can edit Agents, so they do not encounter a 403 only after clicking:

| Location                                                                                                                                                               | Without Conversation Platform permissions                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">AI Features</mark> → <mark style="color:blue;">AI Assistant</mark> → the Agent's <mark style="color:blue;">Conversation Platforms</mark> tab | The <mark style="color:blue;">Platform Settings</mark> and <mark style="color:blue;">Connect Channel</mark> buttons are disabled. Hovering displays "You need Customer Service Conversations → Conversation Platform permissions to open conversation platform settings. Please contact your administrator." <mark style="color:blue;">Go to Conversation</mark> and <mark style="color:blue;">Embed Code</mark> remain available                                                                                                                    |
| <mark style="color:blue;">Customer Service Conversations</mark> in the left menu                                                                                       | <mark style="color:blue;">Conversation Platforms</mark> is hidden. If the role has <mark style="color:blue;">Conversation Platform Analysis permissions</mark>, the analysis page can still be opened directly through a link                                                                                                                                                                                                                                                                                                                        |
| The <mark style="color:blue;">Customer Service Conversations</mark> group in the left menu                                                                             | If only <mark style="color:blue;">Conversation Platform Analysis permissions</mark> is checked under Customer Service Conversations, the entire <mark style="color:blue;">Customer Service Conversations</mark> group is hidden, so it does not expand into an empty group                                                                                                                                                                                                                                                                           |
| Entry points to conversation platform settings on other pages                                                                                                          | After opening a team, the gear icon in each row of the <mark style="color:blue;">Conversation Platforms</mark> list on the left and the <mark style="color:blue;">Manage Tags</mark> link in the conversation tag menu are hidden. Platform names in the <mark style="color:blue;">Credits</mark> → <mark style="color:blue;">Quota Allocation</mark> → <mark style="color:blue;">Conversation Platform Quotas</mark> table and conversation platform IDs in AgentOps evaluation records appear as plain text and cannot be clicked to open settings |

These screens are unaffected for members with Conversation Platform permissions. <mark style="color:blue;">Connect Channel</mark> also requires permission to edit the Agent and <mark style="color:blue;">Allow Adding Conversation Platforms</mark> to be enabled for the role. All three conditions must be met.

{% hint style="info" %}
**Scenario: An AI assistant administrator who only adjusts Agents, without managing conversation platform settings**

An organization administrator wants the "AI Assistant Administrator" role to adjust Agent settings, while leaving conversation platform settings for LINE, websites, and other channels to the customer service supervisor. They check <mark style="color:blue;">AI Assistant permissions</mark> under <mark style="color:blue;">AI Features permissions</mark>, leave <mark style="color:blue;">Conversation Platform permissions</mark> unchecked under Customer Service Conversations, and click <mark style="color:blue;">Save</mark>. When members of this role open an Agent's <mark style="color:blue;">Conversation Platforms</mark> tab, they can still use <mark style="color:blue;">Go to Conversation</mark> and <mark style="color:blue;">Embed Code</mark>. <mark style="color:blue;">Platform Settings</mark> and <mark style="color:blue;">Connect Channel</mark> are disabled, and hovering tells them to ask an administrator for permission. The left menu also hides <mark style="color:blue;">Conversation Platforms</mark>, which they cannot access.
{% endhint %}

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-c1aef39f472dffd51a784596621bac65605d7135%2Frole-permission-no-inbox-permission.png?alt=media" alt="Customer Service Conversation permissions section in role permissions: only Conversation Platform Analysis permissions is checked; Conversation Platform permissions, All Conversations permissions, Transfer Conversations to Others permissions, and Contact permissions are unchecked"><figcaption><p>A role with only Conversation Platform Analysis permissions checked under Customer Service Conversations, without Conversation Platform permissions</p></figcaption></figure>

### Opening a Page Directly Without Permission <a href="#no-permission-page" id="no-permission-page"></a>

When a member opens an existing page that their role lacks permission to access through a colleague's link, a bookmark, or a manually entered URL, the page displays **403**: "Sorry, you do not have permission to view this page. Please ask your organization administrator for the corresponding role permissions." The URL stays the same so the member can forward it directly to the administrator. Click <mark style="color:blue;">Back to Home</mark> to return to the home page.

If a member clicks such a link before logging in, the same screen appears after login instead of redirecting them to the home page.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-fecec1a9ae5e77b7bc19c912296f114534fe2aeb%2Frole-permission-page-denied-403.png?alt=media" alt="403 screen with the message &#x27;Sorry, you do not have permission to view this page. Please ask your organization administrator for the corresponding role permissions.&#x27; and a Back to Home button below"><figcaption><p>Pages the role lacks permission to access display 403 with instructions for requesting access</p></figcaption></figure>

The following two cases still display **404** ("Sorry, the page you are trying to access does not exist."). Changing role permissions will not resolve them:

* The URL is incorrect, or the page does not exist
* The feature has not been enabled for the organization

### Requesting Permission <a href="#request-permission" id="request-permission"></a>

1. The member sends the URL of the page showing 403 to the organization administrator and explains which feature they need
2. The administrator checks the [Permission Structure Overview](#permission-structure-overview) to identify the required permission, then follows [Edit Role Permissions](#edit-role-permissions) to check and save it for the member's role, or [assigns](#assign-members) the member to a role that already has the permission
3. The member refreshes the page to access it, without needing to log in again

{% hint style="info" %}
**Scenario: A customer service representative requests access to conversation platform analysis**

Mei's "Customer Service Representative" role only has <mark style="color:blue;">Conversation Platform permissions</mark>. She cannot see the analysis icon in the <mark style="color:blue;">Conversation Platforms</mark> list. When her supervisor sends her a conversation platform analysis link, she opens it and sees 403, "You do not have permission to view this page." Mei forwards the link to the organization administrator, who checks <mark style="color:blue;">Conversation Platform Analysis permissions</mark> under <mark style="color:blue;">Customer Service Conversation permissions</mark> for the "Customer Service Representative" role and saves. Mei refreshes the page and can view the platform's analysis.
{% endhint %}

***

## Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

### Common Issue: Users Cannot See Expected Features or Can Use More Features Than Expected <a href="#faq-user-cannot-see-expected-features" id="faq-user-cannot-see-expected-features"></a>

1. Check all roles the user belongs to, including whether the default role grants too many permissions. You can also use [View Effective Permissions](https://docs.maiagent.ai/maiagent-user-guide/en/org/overview/member.md#effective-permissions) in the member list to see which role grants each permission
2. Ask the user to clear their browser cache and log in again
3. If an Agent or an Agent in the Agent Marketplace is missing, follow the checklist in [Members Still Cannot See an Agent After Permissions Are Set](#faq-member-cannot-see-agent)
4. If the user sees a full-page "No Access" message after login, their roles do not have any features enabled. Add them to a role with feature permissions, or enable at least one feature for their role, then ask them to click <mark style="color:blue;">Recheck Permissions</mark> on that page. See [How to Log In to the Platform: Why Does the No Access Page Appear After Login?](https://docs.maiagent.ai/maiagent-user-guide/en/start/login.md#faq-no-access)
5. If a user opens a page and sees 403, "Sorry, you do not have permission to view this page," the page exists but their role lacks the required permission. See [What Members See Without Permission](#what-members-see-without-permission)

### Permission Review Recommendations <a href="#permission-audit-recommendations" id="permission-audit-recommendations"></a>

* Regularly review whether users' role assignments are appropriate
* Remove all role assignments for members who have left the organization

***

## Frequently Asked Questions <a href="#faq" id="faq"></a>

### Q: What If Members Still Cannot See an Agent After Permissions Are Set? <a href="#faq-member-cannot-see-agent" id="faq-member-cannot-see-agent"></a>

First identify where the member cannot find the Agent. Different settings determine visibility in each location:

| Where the member cannot find it                                                                                   | Setting that determines visibility                                                                                                                                            |
| ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">Agent Marketplace</mark> is missing from the left menu                                  | The role's <mark style="color:blue;">Agent Marketplace permissions</mark>                                                                                                     |
| The <mark style="color:blue;">Organization-Built</mark> tab in <mark style="color:blue;">Agent Marketplace</mark> | The Agent's "Internal" conversation platform and <mark style="color:blue;">Read</mark> under <mark style="color:blue;">Assign Conversation Platforms</mark>                   |
| The <mark style="color:blue;">Official Built-In</mark> tab in <mark style="color:blue;">Agent Marketplace</mark>  | The official built-in Agent's access audience (configured outside the role permissions page)                                                                                  |
| The Agent list in Agent Builder                                                                                   | <mark style="color:blue;">AI Assistant permissions</mark> and <mark style="color:blue;">Read</mark> for the Agent under <mark style="color:blue;">Assign AI Assistants</mark> |

Then check the following in order:

1. **Check using the member's account, not the owner's account**: The Owner role automatically has access to all resources. An owner being able to see an Agent does not mean a member can see it.
2. **The member has&#x20;**<mark style="color:blue;">**Agent Marketplace permissions**</mark>: This permission is checked for the default role when the organization is created. If it is unchecked and no other role grants it, <mark style="color:blue;">Agent Marketplace</mark> does not appear in the left menu.
3. **The Agent's "Internal" conversation platform is assigned, with&#x20;**<mark style="color:blue;">**Read**</mark>**&#x20;checked**: The <mark style="color:blue;">Organization-Built</mark> tab lists "Internal" conversation platforms the member can read. Assigning only the Agent without its conversation platform will not make it appear in the marketplace. In the <mark style="color:blue;">Assign Conversation Platforms</mark> dialog, use <mark style="color:blue;">All AI Assistants</mark> to filter for the Agent and find its Web, Internal, and API platforms (see [Filter by Agent and Channel Type](#filter-inbox-picker)). For the effect of <mark style="color:blue;">Read</mark>, see [Role Resource Visibility Control](https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/group-resource-visibility.md#read-permission-visibility).
   * Roles selected when creating an Agent, and roles to which the Agent is added through <mark style="color:blue;">Assign AI Assistants</mark>, also receive the Agent's conversation platforms automatically.
   * Adding a role under <mark style="color:blue;">Permission Settings</mark> on the Agent settings page assigns only the Agent itself, without its conversation platforms. Add them separately under <mark style="color:blue;">Assign Conversation Platforms</mark>.
4. **The same role has both the Agent and&#x20;**<mark style="color:blue;">**Agent Marketplace permissions**</mark>: If only the conversation platform is assigned, members can see the Agent and start conversations, but actions such as renaming, deleting, or pinning conversations are denied. These actions check whether any one of the member's roles both has <mark style="color:blue;">Agent Marketplace permissions</mark> (or a permission under <mark style="color:blue;">Customer Service Conversation permissions</mark>) and is assigned the Agent. Having the permission in role A and the Agent in role B does not count.
5. **Check what is assigned to the default role**: The default role applies automatically to all members. All members can see Agents and conversation platforms assigned to it. When creating an Agent, <mark style="color:blue;">Permission Settings</mark> selects all roles except the default role by default. Selecting <mark style="color:blue;">All Roles</mark> also assigns the default role.
6. **For Agent Teams, assign the team's entry Agent**: When a team is created, the system creates an entry Agent with the same name as the team, but does not assign it to any role. Add this entry Agent under the role's <mark style="color:blue;">Assign AI Assistants</mark> (its conversation platforms are assigned automatically). Members can then see the team in the <mark style="color:blue;">Organization-Built</mark> tab and rename or delete team conversations.
7. **The Agent's "Internal" conversation platform is enabled**: The marketplace does not list the platform if <mark style="color:blue;">Enabled</mark> is turned off in its [Function Settings](https://docs.maiagent.ai/maiagent-user-guide/en/build/conversation-settings/platform-settings/function-settings.md#basic-functions).
8. **Ask the member to refresh the page**: Permission and assignment changes take effect when the member refreshes or reopens the page.

{% hint style="info" %}
For the complete conditions for listing Agents in the <mark style="color:blue;">Organization-Built</mark> tab, see [What Are Official Built-In Agents: Which Agents Appear in the Organization-Built Tab?](https://docs.maiagent.ai/maiagent-user-guide/en/work/built-in-agents.md#self-built-tab-conditions). To manage access to official built-in Agents, configure their access audience; see [Configure the Access Audience](https://docs.maiagent.ai/maiagent-user-guide/en/org/management.md#group-permissions).
{% endhint %}

### Q: How Can New Members Get More Permissions? <a href="#faq-grant-more-permissions" id="faq-grant-more-permissions"></a>

Administrators can assign additional roles to members in the following ways:

* **Individual member**: Click the member in the member list and add roles manually
* **Batch assignment**: Use [Member Management: Batch Member and Permission Management](https://docs.maiagent.ai/maiagent-user-guide/en/org/overview/member.md#batch-member-permission-management) to assign roles to multiple people at once through Excel
* **Automatic EIP synchronization**: If EIP login is used, configure roles in EIP to synchronize them automatically at login ([Third-Party Login (SSO)](https://docs.maiagent.ai/maiagent-user-guide/en/org/sso.md))

### Q: Why Can't the Default Role Be Assigned in Batches Through Excel? <a href="#faq-default-role-excel-batch" id="faq-default-role-excel-batch"></a>

The default role is the base role that all members have automatically. The system assigns it to every member, so assigning it through Excel is neither necessary nor allowed.

### Q: Why Can't Agents, Knowledge Bases, or Conversation Platforms Be Assigned to the Owner Role? <a href="#faq-owner-role-cannot-assign-resources" id="faq-owner-role-cannot-assign-resources"></a>

The Owner role has full access to all resources and requires no additional assignments. The system automatically grants the Owner role access to every resource in the organization.

### Q: What Does the Permission Hierarchy Mean? <a href="#faq-permission-hierarchy-meaning" id="faq-permission-hierarchy-meaning"></a>

MaiAgent permissions use a parent-child hierarchy. For example, "AI Features permissions" is a parent permission containing child permissions such as "AI Assistant permissions," "Knowledge Base permissions," "Crawler permissions," and "Tool permissions." Checking the parent permission automatically includes all child permissions. You can also check only specific child permissions for more precise 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/role-permission.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
