> 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/maigpt-role-permissions.md).

# MaiGPT Role Usage Permissions

Configure the MaiGPT models, tools, skills, connectors, and built-in features available to different roles.

Organization administrators can restrict the models, tools, skills, connectors, and built-in features available in MaiGPT by role. When a member has multiple roles, the system combines the permissions granted by each role. The member can use an item as long as at least one role allows it.

{% hint style="info" %}
Owners are not subject to role usage scope restrictions. The settings below apply to both default and custom roles.
{% endhint %}

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

An IT manager wants the customer service role to use only company-approved models. They open the role's MaiGPT usage permissions, clear "All" under "Available Models," and select the approved models. The card immediately shows "Partial" and the number selected, and a success message appears. Tools, skills, and connectors retain their own "All" settings; changing the model scope does not restrict them.

## Configure a Role's MaiGPT Usage Scope <a href="#configure-scope" id="configure-scope"></a>

{% stepper %}
{% step %}

### 1. Open Role Permissions <a href="#open-role-permissions" id="open-role-permissions"></a>

Go to <mark style="color:blue;">Organization Settings</mark> → <mark style="color:blue;">Organization Overview</mark>, then select <mark style="color:blue;">Edit Role Permissions</mark> in the "Management" section.
{% endstep %}

{% step %}

### 2. Select a Role <a href="#choose-role" id="choose-role"></a>

Find a default or custom role in the role list, select <mark style="color:blue;">Edit</mark> on the right, then open the <mark style="color:blue;">Assign MaiGPT Usage Permissions</mark> tab.
{% endstep %}

{% step %}

### 3. Set the Available Scope <a href="#set-available-scope" id="set-available-scope"></a>

Under "Available Scope," configure <mark style="color:blue;">Available Models</mark>, <mark style="color:blue;">Tools</mark>, <mark style="color:blue;">Skills</mark>, and <mark style="color:blue;">Connectors</mark> separately. Each card has its own "All" checkbox. Click a category name to expand or collapse its list of items.

| Category setting                   | What members can use                                                  |
| ---------------------------------- | --------------------------------------------------------------------- |
| "All" selected                     | Every available item in the category; the list is grayed out          |
| "All" cleared, some items selected | Only selected items; the card shows "Partial" and the number selected |
| "All" cleared, no items selected   | This role grants no access to the category; the card shows "None"     |

To restrict a category, clear its "All" checkbox, then select the permitted items from the list that opens automatically. Selecting "All" again clears individual selections. If you clear "All" later, you must select the items again.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-84b3e5ddfa1ba53be75b55c1591eec205e7af5cf%2Fmaigpt-role-scope-overview.png?alt=media" alt="Four available-scope cards, each with its own All checkbox"><figcaption><p>Configure Available Models, Tools, Skills, and Connectors separately</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-90f50a8d54f35895d2596939d50120557c4b9d2e%2Fmaigpt-role-model-none.png?alt=media" alt="The card shows None when All is cleared and no available models are selected"><figcaption><p>When no model is selected, this role grants access to no models</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-e3cb74069c81259c668c473925737d43ab08c228%2Fmaigpt-role-model-partial.png?alt=media" alt="After one available model is selected, the card shows Partial 1/48"><figcaption><p>The card shows Partial and the number selected; the total changes with the models available to the organization</p></figcaption></figure>

{% hint style="warning" %}
If "Available Models" shows "None," the page warns that this role will have no model to select and cannot chat in MaiGPT, but you can still keep this setting. Confirm whether members with this role need to chat in MaiGPT.
{% endhint %}
{% endstep %}

{% step %}

### 4. Configure Built-in Features <a href="#set-built-in-features" id="set-built-in-features"></a>

Under "Features," enable or disable the following capabilities:

* <mark style="color:blue;">Code Interpreter</mark>: Runs code and generates charts, spreadsheets, or documents.
* <mark style="color:blue;">Knowledge Base RAG</mark>: Uses the organization's knowledge bases to answer questions and cite sources.
* <mark style="color:blue;">Deep Research</mark>: Breaks down questions and searches the web in multiple rounds. It uses its own web search and is unaffected by whether the official search tool is enabled.
* <mark style="color:blue;">Browser Tool</mark>: Operates a browser, opens pages, interacts with webpage elements, and captures screenshots.

Changes are saved automatically, so you do not need to click "Save." You can leave the page after the update success message appears. If saving fails, the page identifies the item that was not updated and restores it to its last successfully saved state.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-a98fb627bb61dc4e93ebffb9b022cc16b413af85%2Fmaigpt-role-features.png?alt=media" alt="Four feature toggles on the Assign MaiGPT Usage Permissions page"><figcaption><p>Manage MaiGPT built-in features in role settings</p></figcaption></figure>
{% endstep %}
{% endstepper %}

## What Members See <a href="#member-experience" id="member-experience"></a>

After the role settings take effect, MaiGPT displays only the models, tools, skills, and feature entry points available to the member. If knowledge base retrieval or Code Interpreter was previously available but has been disabled for the role, the right panel explains that the feature is not yet available to the role.

If a connector has been enabled by the organization but is not yet available to the member's role, the member will not see the authorization button and can submit an access request instead. If the member previously completed authorization, they can still disconnect it to remove credentials they no longer use.

{% hint style="warning" %}
After permissions are changed, if an existing conversation uses a model that is no longer allowed, the system attempts to switch to a model available to the role. Remind members to confirm the model name before continuing the conversation.
{% endhint %}

## Related Guides <a href="#related-guides" id="related-guides"></a>

* [Role Permission Management](/maiagent-user-guide/en/org/roles/role-permission.md)
* [MaiGPT Connectors](/maiagent-user-guide/en/work/maigpt/connectors.md)


---

# 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/maigpt-role-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.