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

# Configure Role Permissions in Bulk

Apply the same permission settings to multiple custom roles at once, preview which items each role will gain or lose before applying, and create new roles at the same time.

When an organization has a dozen or more department roles, adding the same new Agent to each role, or removing the same feature from each, used to mean opening every role's edit page one by one. <mark style="color:blue;">Batch Set Permissions</mark> lets you prepare one set of permission settings, select the roles to apply it to, and write it to all of them at once. Before you apply, each role shows how many items it will gain and lose, and you can expand a role to see the details.

## Before You Start <a href="#before-you-start" id="before-you-start"></a>

* **Who can use it**: You need the organization overview permission, that is, you must be an administrator who can open the <mark style="color:blue;">Edit Role Permissions</mark> page.
* **Full overwrite**: For every selected role, the settings on all tabs become exactly the same as this set of settings. Permissions and resource assignments that a role had but this set does not include are removed; the batch does not only “add” on top.
* **Roles you can apply to**: Custom roles only. The owner role and default roles are not in the list and will not be overwritten.
* **Up to 50 roles at a time**: The selected existing roles plus the new roles together can total at most 50.
* **Written only if everything succeeds**: If writing to any one role fails, none of the roles in the batch are changed.
* **Tabs covered**: <mark style="color:blue;">Role Permissions</mark>, <mark style="color:blue;">Assign MaiGPT Usage Permissions</mark>, and eight resource tabs: <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>. Role members and Credit quotas are not affected.
* **Official built-in Agents are not affected**: Locked official built-in Agents and their conversation platforms are not changed by batch settings.

## Use Case <a href="#scenario" id="scenario"></a>

The HR department has launched an “Internal Policy Q\&A” Agent, and the organization administrator wants all 12 department roles to be able to use it. These department roles were all created from the same standard template. In the role list, she clicks <mark style="color:blue;">Batch Set Permissions</mark>, chooses <mark style="color:blue;">Use Existing Role Permissions</mark> with the “Sales” role as the starting point, and adds the Agent on the <mark style="color:blue;">Assign AI Assistants</mark> tab; its conversation platforms are brought in along with it. At <mark style="color:blue;">Apply to Which Roles</mark>, she selects the 12 department roles. Most roles show only additions, with revoked items at “−0”, but “Customer Service” shows “−2 revoked”. Expanding it reveals that Customer Service was later assigned two knowledge bases that the standard template does not include, and a full overwrite would remove them. She deselects Customer Service and adds the Agent to that role separately on its role edit page, and the remaining 11 roles are updated in one go.

## Steps <a href="#steps" id="steps"></a>

{% stepper %}
{% step %}

### 1. Open Batch Set Permissions <a href="#open-batch-permissions" id="open-batch-permissions"></a>

Go to <mark style="color:blue;">Organization Settings</mark> → <mark style="color:blue;">Organization Overview</mark>, click <mark style="color:blue;">Edit Role Permissions</mark> in the <mark style="color:blue;">Management Actions</mark> area, and then click <mark style="color:blue;">Batch Set Permissions</mark> at the top right of the role list.

<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 Set Permissions button at the top right of the role list"><figcaption><p>The Batch Set Permissions entry at the top right of the role list</p></figcaption></figure>

The step bar at the top of the page shows, in order, <mark style="color:blue;">Setup Method</mark>, <mark style="color:blue;">Set Permissions</mark>, and <mark style="color:blue;">Apply to Which Roles</mark>.
{% endstep %}

{% step %}

### 2. Choose a Setup Method <a href="#choose-method" id="choose-method"></a>

| Setup Method                                                   | Description                                                                                                                                                                                       |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">New Permission Rules</mark>          | Start from a blank slate with no settings on any tab. <mark style="color:blue;">Role Permissions</mark> requires at least one feature permission to be checked before you can go to the next step |
| <mark style="color:blue;">Use Existing Role Permissions</mark> | Pick a role from the table below and use its current settings on all tabs as the starting point. The role itself is not changed                                                                   |

When you use an existing role, the table lists all roles in the organization (including the owner and default roles), and you can search by role name or ID. After you select one, “Using the settings of … as the starting point” appears below. Click <mark style="color:blue;">Next</mark>.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-23daa1cb3a8bf431c0b5dce79913154ddb069a79%2Frole-batch-permissions-copy-source.png?alt=media" alt="With Use Existing Role Permissions selected as the setup method, the table lists the organization&#x27;s roles, and the selected role is shown below"><figcaption><p>Use Existing Role Permissions: pick a role as the starting point</p></figcaption></figure>

{% hint style="warning" %}
Using the owner role as the starting point brings in all feature permissions and every resource the organization can currently assign. Before applying, make sure the target roles really need that much access.
{% endhint %}
{% endstep %}

{% step %}

### 3. Set Permissions <a href="#edit-settings" id="edit-settings"></a>

The tabs and operations in this step are the same as on the role edit page. For details, see [Role Permission Management](https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/role-permission.md#edit-role-permissions). The difference is that you are editing a draft here, and nothing is written until you click apply in the <mark style="color:blue;">Apply to Which Roles</mark> step.

* If you used an existing role, changed items are tagged <mark style="color:blue;">Compared with starting point: Added</mark> or <mark style="color:blue;">Compared with starting point: Revoked</mark> (shown as <mark style="color:blue;">Added</mark> / <mark style="color:blue;">Revoked</mark> inside resource tables), indicating the difference from the starting role.
* When you add an Agent on <mark style="color:blue;">Assign AI Assistants</mark>, that Agent's conversation platforms are brought in as well, the same as on the role edit page.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-2461cabd095cf788caf18881d12508e9e1d9963d%2Frole-batch-permissions-compared-mark.png?alt=media" alt="The ten tabs of the second step; after a permission is checked, “Compared with starting point: Added” appears on the right"><figcaption><p>Changed items show their difference from the starting point</p></figcaption></figure>

When you are done, click <mark style="color:blue;">Next</mark>.
{% endstep %}

{% step %}

### 4. Choose the Roles to Apply to and Preview the Differences <a href="#choose-targets" id="choose-targets"></a>

The table lists all custom roles. You can search by role name and check the roles to apply to. The <mark style="color:blue;">Difference After Applying</mark> column shows how each role changes after applying:

| Display              | Meaning                                                                                           |
| -------------------- | ------------------------------------------------------------------------------------------------- |
| +N added, −N revoked | The number of items this role will gain and lose after applying                                   |
| Same as this setting | The role's current settings already match this set of settings, so nothing changes after applying |
| Starting role · …    | The starting role you chose in the setup method                                                   |

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-0d36978c5ebaa05da1015252ee6ffac6741e8417%2Frole-batch-permissions-targets.png?alt=media" alt="After roles are selected in the third step, each row shows the number of added and revoked items, with a full-overwrite reminder at the bottom"><figcaption><p>Each selected role lists the number of items it will gain and lose after applying; expand a row for details</p></figcaption></figure>

Click <mark style="color:blue;">Expand</mark> on a row to see the details:

* <mark style="color:blue;">Will add N items</mark> and <mark style="color:blue;">Will revoke N items</mark> are listed item by item for each tab. Conversation platforms show their channel type, so you can tell apart the different platforms of the same Agent.
* When items are revoked, a notice shows how many members the role has: if no other role provides the revoked items to those members, they will lose them after applying.
* When the entry point of a feature area will be turned on or off by this application, an extra notice says “The entry point for this area will also be turned on / off (not counted in the item total)”.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-fe67acb259067ea21aa9a310597d136cd2c8c142%2Frole-batch-permissions-expand.png?alt=media" alt="After a role is expanded, the items to be added and revoked are listed by tab"><figcaption><p>The expanded details list the items to be added and revoked by tab</p></figcaption></figure>

**Create roles at the same time**: Click <mark style="color:blue;">Add Role</mark> above the table, and the table gains a blank row labeled <mark style="color:blue;">New Role</mark>; just enter a role name. The new role is created when you apply, with exactly this set of permissions. The name cannot be blank and cannot duplicate an existing role or another new role in the same batch. If it duplicates an existing role, you can rename it or simply check that existing role instead.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-5ce52e32b86c147956f8c1cfa57dd8ab1408413f%2Frole-batch-permissions-new-role.png?alt=media" alt="A new role row appears at the top of the table; after you enter a name, the role is created when you apply"><figcaption><p>When you add a role, the table gains a new role row</p></figcaption></figure>
{% endstep %}

{% step %}

### 5. Apply <a href="#apply" id="apply"></a>

After you confirm the “Full overwrite” reminder at the bottom, click <mark style="color:blue;">Apply to N roles</mark>. On success, “Applied to N roles” is shown and you return to the role list.

* While applying, you cannot change the selection, go back a step, or leave the page, so that the changes are not applied only halfway.
* If someone modifies one of the roles after you viewed the differences, the screen shows “The role was modified after you viewed the differences and has been recalculated” and updates the preview. Review the differences again before applying.
  {% endstep %}
  {% endstepper %}

{% hint style="warning" %}
Applied changes are not reverted automatically. To change them back, run another batch setting, or adjust each role on its edit page. If you leave the page before applying, the screen reminds you that “Settings that have not been applied will be lost”.
{% endhint %}

## Verifying After You Apply <a href="#verify" id="verify"></a>

To check which permissions a member actually has after applying, and which role each one comes from, click <mark style="color:blue;">View Effective Permissions</mark> for that member in the member list. For details, see [Member Management: View a Member's Effective Permissions](https://docs.maiagent.ai/maiagent-user-guide/en/org/overview/member.md#effective-permissions).

## FAQ <a href="#faq" id="faq"></a>

### Q: Why are the owner and default roles not in the apply list? <a href="#faq-owner-default-not-listed" id="faq-owner-default-not-listed"></a>

The owner role always has all permissions, and the default role is automatically applied to all members, so neither is suitable for a full overwrite and neither is in the apply list. They can still be chosen as the starting point in <mark style="color:blue;">Setup Method</mark>. To adjust the default role, edit it on its role edit page.

### Q: How is this different from “Duplicate Role”? <a href="#faq-vs-duplicate-role" id="faq-vs-duplicate-role"></a>

[Duplicate Role](https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/role-permission.md#duplicate-role) creates a new role that carries over the source role's permissions and resource assignments, but not its members. Batch Set Permissions also does not carry over members, but it can apply to multiple existing roles at once.

### Q: What if I need to change more than 50 roles at once? <a href="#faq-over-limit" id="faq-over-limit"></a>

When you exceed the limit, the bottom of the page shows “You can apply to at most 50 roles at a time” and the apply button cannot be clicked. Apply in several batches; each batch can use the same starting role to get the same settings. If the list has more than 50 roles, first narrow it down with a role name keyword, then select all with the checkbox in the table header; roles you checked earlier are kept when you change the keyword.


---

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