For the complete documentation index, see llms.txt. This page is also available as Markdown.

Agent Teams: Role Resource Authorization

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 in the user manual.

Four Permissions

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

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

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

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.

Last updated

Was this helpful?