> 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.md).

# Roles and Permissions

Roles are how MaiAgent controls who can see what and who can do what. These pages explain how to use roles, from configuration to planning.

Roles determine which features members can see, whether they can create items, and which Agents and knowledge bases they can access. Choose a page based on what you want to do:

<table><thead><tr><th width="260">What do you want to do?</th><th>Read this page</th></tr></thead><tbody><tr><td>Learn about role types, create roles, and select feature permissions</td><td><a href="https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/role-permission.md">Role Permission Management</a></td></tr><tr><td>Apply the same permission settings to multiple roles at once, or find out which role a member's permission comes from</td><td><a href="https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/role-batch-permissions.md">Batch Role Permission Settings</a>, <a href="https://docs.maiagent.ai/maiagent-user-guide/en/org/overview/member.md#effective-permissions">View a Member's Effective Permissions</a></td></tr><tr><td>Control which Agents and knowledge bases a role can see and use</td><td><a href="https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/group-resource-access.md">Role Resource Access Permissions</a></td></tr><tr><td>Filter the member list by role</td><td><a href="https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/group-member-filtering.md">Role Member Filtering</a></td></tr><tr><td>Understand the difference between roles and contacts</td><td><a href="https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/contact-role-comparison.md">Differences Between Roles and Contacts</a></td></tr><tr><td>Let colleagues create Agents while requiring approval and staged publishing for sharing</td><td><a href="https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/role-design-guide.md">Role Permission Planning Guide</a></td></tr><tr><td>Restrict customer service from transferring conversations that other colleagues are handling</td><td><a href="https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/transfer-others-permission.md">Permission to Transfer Others' Conversations</a></td></tr></tbody></table>

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

The planning guide explains how to divide up your roles; the other pages explain where the buttons are and how to configure them. When planning your organization's roles for the first time, read the planning guide first, then come back and configure each page accordingly.
{% endhint %}

## Batch Permission Settings and Members' Effective Permissions <a href="#role-permission-governance" id="role-permission-governance"></a>

When there are many roles, editing them one by one makes it easy to miss one, and it is hard to tell at a glance which role grants a member's permission. The role list and the member list each have an entry point, and both require the Organization Overview permission (administrators who can access <mark style="color:blue;">Edit Role Permissions</mark> and the member management page):

* **Batch permission settings**: In the role list, click <mark style="color:blue;">Batch Permission Settings</mark>. First prepare a permission configuration (start from blank, or take the settings of an existing role), then select the custom roles to apply it to; you can also add new roles at the same time. Before applying, the system lists the items each role will gain or lose, and writes everything at once after you confirm. For instructions, see [Batch Role Permission Settings](https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/role-batch-permissions.md).
* **View effective permissions**: In the member list, click the shield icon in the member's action column to see the feature permissions, MaiGPT usage scope, and resources the member actually has after all their roles are merged, along with which roles grant each item. For instructions, see [Member Management: View a Member's Effective Permissions](https://docs.maiagent.ai/maiagent-user-guide/en/org/overview/member.md#effective-permissions).

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-288b2e260222c37bc1837a1447ef6314b72898bc%2Frole-batch-permissions-entry.png?alt=media" alt="The Batch Permission Settings button at the top right of the role list"><figcaption><p>The Batch Permission Settings entry at the top right of the role list</p></figcaption></figure>


---

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