> 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/tech/en/identity-and-access/agent-team-permissions.md).

# Agent Teams: Role Resource Permissions

Integrate role-based resource permissions for Agent Teams, separating use, conversation history access, editing, and deletion without treating team channels as independent permission sources.

When an integrated system assigns an Agent Team to a role, permissions apply to the team. The team's entry Agent and that Agent's conversation channels inherit the team permissions, so you do not need to assign separate permissions to each channel.

For example, an enterprise integration administrator wants a customer service role to use a specific team without viewing other people's conversations or modifying the team. Assign the team to the role and keep the default "Use" permission. Grant "View conversation history" separately when a supervisor needs to review past conversations.

For instructions on using the admin console, see [Agent Teams](https://docs.maiagent.ai/build/teams) in the user manual.

## Four Permissions <a href="#permission-flags" id="permission-flags"></a>

| Permission Field       | Purpose                                                                           | Default for New Assignments |
| ---------------------- | --------------------------------------------------------------------------------- | --------------------------- |
| `canRead`              | Use the team and converse with it through the entry Agent's conversation channels | `true`                      |
| `canViewConversations` | View the team's conversation history and execution logs                           | `false`                     |
| `canUpdate`            | Modify the team canvas, members, and entry settings                               | `false`                     |
| `canDelete`            | Delete the team                                                                   | `false`                     |

{% hint style="warning" %}
Viewing conversation history, editing, and deletion all depend on "Use". When updating permissions, you must also disable the other three permissions if you disable `canRead`; otherwise, the request is rejected.
{% endhint %}

When a member belongs to multiple roles, each of the four permissions for the same team is combined across roles using a union. Removing one role's grant does not necessarily remove the member's access; check the other roles as well. Organization owners have all four permissions.

## Assignment and Updates <a href="#assign-and-update" id="assign-and-update"></a>

The following paths are relative to `/api/organizations/{organizationId}/groups/{groupId}/group-teams/`. `{grantId}` is the permission grant record ID, which differs from the team ID.

| Method   | Relative Path  | Purpose                                                                        |
| -------- | -------------- | ------------------------------------------------------------------------------ |
| `GET`    | Root path      | List the role's team permission grants                                         |
| `POST`   | `bulk-create/` | Assign teams with `{"teams":["<teamId>"]}`; teams already assigned are skipped |
| `PATCH`  | `{grantId}/`   | Update the four permissions for this grant                                     |
| `DELETE` | `{grantId}/`   | Remove this role's permission grant                                            |

The `team` object in the response contains the team's `id`, `name`, and the entry Agent's `inboxes`, which you can use to show which conversation channels the team permission grant covers. Use the returned grant `id` to update or remove permissions; do not use `team.id` as the grant ID.

Only assignable teams within the same organization can be specified. The role is first looked up in the caller's current organization; a role in another organization returns `404`. Permissions for the owner role cannot be modified. Listing and writing permission grants are also subject to the "Organization overview" permission check.

## Team Operations Still Require Feature and Plan Checks <a href="#feature-and-plan-gates" id="feature-and-plan-gates"></a>

Resource permissions determine what actions are allowed on which teams. They do not replace feature toggles or plan eligibility. Managing teams remains subject to the platform's Agent Teams toggle and team feature permissions; creating a team also requires the role to allow adding teams. Creating or deleting a team, or modifying or upgrading its entry, must also pass Agent Builder plan checks.

Reading execution logs first requires passing the platform feature toggle and the feature permission check for access to execution logs. Once these checks pass, the response is `404` if the caller lacks permission to use the team, or `403` if the caller has use permission but lacks permission to view conversation history.

Existing permissions for regular Agents or conversation channels do not grant additional permissions to a team's entry Agent or team channels. Integrations should maintain team permissions and avoid assigning regular channel permissions to each team channel individually, which can cause configured permissions to differ from actual permissions.


---

# 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/tech/en/identity-and-access/agent-team-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.
