> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/org/group-resource-access.md).

# Role Resource Access Permissions

### Feature Overview

Role resource access permissions is an advanced permission management feature in MaiAgent that allows organization administrators to granularly control role members' "visibility" and "usage permissions" for resources such as AI assistants, knowledge bases, and conversation platforms. With this feature, you can implement more refined permission control, ensuring sensitive resources are only visible to specific roles.

{% hint style="info" %}
This feature is based on the RBAC (Role-Based Access Control) concept and provides two layers of permission control:

* **Usage permission**: Whether the resource can be used
* **Access permission**: Whether the resource is visible in resource lists
  {% endhint %}

***

### Permission Level Descriptions

#### Two-Layer Permission Control

MaiAgent's resource permissions are divided into two levels:

<table><thead><tr><th width="180">Permission Type</th><th width="200">Description</th><th>Scope of Impact</th></tr></thead><tbody><tr><td><strong>Usage Permission</strong></td><td>Determines whether the resource can be used</td><td>Performing operations, sending messages, modifying settings</td></tr><tr><td><strong>Access Permission (Visibility)</strong></td><td>Determines whether the resource is visible in lists</td><td>Resource menus, dropdown lists, search results</td></tr></tbody></table>

#### Permission Combination Scenarios

| Usage Permission | Access Permission | Result                                                                       |
| ---------------- | ----------------- | ---------------------------------------------------------------------------- |
| ✅ Yes            | ✅ Yes             | Can see and use the resource (highest permission)                            |
| ✅ Yes            | ❌ No              | Can use but cannot see the resource (suitable for API integration scenarios) |
| ❌ No             | ✅ Yes             | Can see but cannot use the resource (read-only permission)                   |
| ❌ No             | ❌ No              | No access at all (default state)                                             |

***

### Setting Access Permissions

#### Prerequisites

1. You must be the organization owner or a member with role permission management authority
2. Roles have been created and relevant resources (AI assistants, knowledge bases, or conversation platforms) have been assigned

#### Steps

1. **Navigate to the role management page**
   * Click "<mark style="color:blue;">Organization Settings</mark>" in the left menu
   * Click "<mark style="color:blue;">Role Permission Management</mark>"
   * Select the role to edit
2. **Select the resource type tab**
   * Click the "<mark style="color:blue;">Assign AI Assistants</mark>", "<mark style="color:blue;">Assign Knowledge Bases</mark>", or "<mark style="color:blue;">Assign Conversation Platforms</mark>" tab
3. **Edit access permissions**
   * In the list of assigned resources, find the resource to edit
   * Click the "<mark style="color:blue;">Edit</mark>" button on the right side of the resource
   * In the "Edit Access Permissions" dialog, check or uncheck the "<mark style="color:blue;">Visibility</mark>" option
   * Click "<mark style="color:blue;">Confirm</mark>" to save the settings

{% hint style="warning" %}
After changing access permissions, affected members need to log in again or refresh the page to see the changes.
{% endhint %}

***

### Use Case Examples

#### Scenario 1: Confidential Project Management

**Need**: The R\&D department has a confidential AI assistant for a project and wants only project members to see it

**Configuration**:

* Create a "R\&D Project Team" role
* Assign the confidential AI assistant to this role
* ✅ Enable "Visibility" permission
* Other roles cannot see this confidential assistant even if they have AI assistant usage permissions

#### Scenario 2: API Integration

**Need**: An AI assistant is intended only for external system API calls and should not be visible to internal employees in the interface

**Configuration**:

* Assign the AI assistant to the API integration role
* ✅ Grant usage permission (so the API can call it)
* ❌ Disable "Visibility" permission (not displayed in the interface list)

#### Scenario 3: Hierarchical Data Access

**Need**: Allow entry-level employees to see only public knowledge bases while managers can see all knowledge bases

**Configuration**:

* "Regular Employee" role: Assign only public knowledge bases with visibility enabled
* "Manager" role: Assign all knowledge bases with visibility enabled for all
* "Finance Specialist" role: Assign financial knowledge bases with visibility enabled

***

### Relationship with Existing Permissions

#### Permission Calculation Logic

A member's final resource access permission = **Role Permission** + **Resource Assignment** + **Access Permission Setting**

```
Example: Member Xiao Wang has two roles simultaneously

Role A:
- AI feature permission: ✅
- Assigned AI Assistant X: ✅ Usage permission, ✅ Visibility

Role B:
- AI feature permission: ✅
- Assigned AI Assistant Y: ✅ Usage permission, ❌ Visibility

→ Xiao Wang's actual permissions:
- Can see and use AI Assistant X
- Can use AI Assistant Y (via API or direct link), but cannot see it in the interface list
```

#### Difference from Owner Role

{% hint style="info" %}
The **Owner Role** automatically has full access permissions for all resources (including both usage permission and visibility), with no manual configuration required.
{% endhint %}

***

### FAQ

#### Q: Why separate "usage permission" and "access permission"?

**A**: This design provides more flexible permission control:

* **Simplified interface**: Prevents members from seeing too many irrelevant resources, improving user experience
* **Data security**: Sensitive resources can be completely hidden, reducing the risk of information leaks
* **API integration**: Supports system-to-system integration without displaying technical resources in the user interface

#### Q: If a member has the same resource through multiple roles, how is access permission calculated?

**A**: The "union" principle is used. As long as any role enables visibility, the member can see the resource.

#### Q: How long does it take for access permission changes to take effect?

**A**: Changes take effect immediately, but affected members need to refresh the page or log in again to see the changes.

#### Q: After disabling visibility, can the member still use the resource via API?

**A**: Yes. As long as the member has usage permission for the resource, they can use it via API or direct link, even if it is not visible in the interface.

#### Q: How can I quickly batch-set visibility for multiple resources?

**A**: Currently, resources must be edited one by one. Plan your visibility strategy when assigning resources to avoid large-scale adjustments later.

***

### Additional Use Cases

Beyond the scenarios above, resource visibility control is particularly useful in the following situations:

* **Multi-department collaboration**: The marketing department only needs to see marketing-related AI assistants and knowledge bases, while the customer service department only needs to see customer service-related resources, preventing members from being distracted by irrelevant resources
* **Project grouping**: Set independent resource visibility scopes for different project teams to avoid resource confusion between projects
* **Permission testing**: When testing new features, hide test resources so regular members cannot see them
* **Onboarding guidance**: Set fewer visible resources for new members to reduce the learning curve
* **Outsourcing team management**: Allow outsourced personnel to see only resources related to their assigned projects, protecting other project information

{% hint style="warning" %}
Keep "visibility" and "usage permission" consistent to avoid situations where members can see resources they cannot use, which causes confusion.
{% endhint %}

***

### Important Notes

{% hint style="warning" %}
**Permission Configuration Recommendations**

* Configure access permissions for the default role carefully to avoid all members seeing unnecessary resources
* Regularly review resource visibility settings to ensure compliance with organizational security policies
* Restrict visibility for important or sensitive resources, opening access only to specific roles
  {% endhint %}

{% hint style="info" %}
If a resource is deleted or deactivated, members cannot see or use it even if it remains in the visibility list.
{% endhint %}

{% hint style="info" %}
**Related Documentation**

* [Role Permission Management](/maiagent-user-guide/maiagent-user-guide-en/org/role-permission.md)
* [Organization and Member Management](https://github.com/Playma-Co-Ltd/maiagent-user-guide-gitbook/blob/main/en/org/rbac.md)
* [Batch Member and Permission Management](https://github.com/Playma-Co-Ltd/maiagent-user-guide-gitbook/blob/main/en/org/bulk-role-permission.md)
  {% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/org/group-resource-access.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.