Share access to an Agent

Overview

An Agent remains owned by its Organization. Sharing grants authority over that Agent; it does not transfer ownership of the underlying resource.

New Agents use Restricted General access by default. Their creator receives a direct Agent Owner assignment when the Agent is created.

Organization Owners and Organization Admins always have full authority over Agents in their Organization. They are not listed as direct assignments in the Share dialog.

Agent access model

Agent Barn calculates effective authority from all applicable sources.

• Implicit Organization authority
• +
• Direct Agent Access
• +
• Agent General Access
• Effective Agent Permissions

Permissions are allow-only. One access source cannot reduce Permissions granted by another.

For an ordinary Organization Member:

• No direct grant and Restricted General access means no Agent access.
• A direct grant gives the Member its selected Agent Access Role.
• General access gives the Member its configured role automatically.
• When both apply, the Member receives the union of both Permission sets.

Agent Access covers the complete Agent aggregate, including:

• Agent metadata
• Configuration
• Lifecycle operations
• Conversations
• Tool Calls
• Activity
• Logs
• Agent-specific costs
• Skills
• Credential metadata and management, when permitted
• Access management, when permitted

Secret plaintext is never returned through read access.

Compare Agent Access Roles

Every Organization includes three locked Agent Access Roles.

The Permission progression is cumulative.

1. Agent Viewer Read the Agent, its activity, and its costs
2. Agent Editor Viewer authority, plus configuration, lifecycle, Skills, and Agent Secrets
3. Agent Owner Editor authority, plus retirement and access management

Agent Viewer

Use Agent Viewer for people who need to:

• Inspect the Agent
• Review Conversations and Tool Calls
• Review health and Logs
• Review Agent-specific costs
• Diagnose behavior without changing it

Agent Viewer is the recommended starting role when someone needs visibility but not operational control.

Agent Editor

Use Agent Editor for people who need to:

• Configure the Agent
• Start and Pause the Agent
• Assign or repin Skills
• Manage platform and integration credentials
• Apply configuration changes that restart the Runtime

Agent Editor includes sensitive operational authority. An Editor can alter how the Agent behaves, and which credentials it uses.

Agent Owner

Use Agent Owner only for trusted administrators who need to:

• Perform every Editor operation
• Retire the Agent
• Open Share
• Grant, change, or remove other Members’ access
• Configure Agent General Access
• Grant Agent Owner to other Members

An Organization may also define custom Agent Access Roles. When custom roles are available, review their actual Permission summary rather than inferring authority from the role name.

Before you begin

You need:

• Access to the Organization that owns the Agent
• Access to the Agent
• The agent.access.manage Permission
• The recipient already added to the same Organization
• The recipient’s invitation accepted
• A clear reason for the requested level of access
• A decision between direct access and Agent General Access
• A plan for verifying the recipient’s effective authority

The locked Agent Owner role includes agent.access.manage. Organization Owners and Organization Admins also have implicit authority to manage Agent access.

If the Share action is missing, your effective Permissions do not include access management.

How additive Permissions work

Direct Agent Access and Agent General Access are both positive grants.

With custom roles, the combined Permission set may not correspond to one named role. For example:

Custom direct role:
- View
- See activity
- Manage access

General Access role:
- View
- Edit

Effective Permissions:
- View
- See activity
- Manage access
- Edit

Neither role overrides the other.

To reduce effective authority, remove or change every source granting the unwanted Permission.

Special access cases

Organization Owner and Organization Admin

Organization Owners and Organization Admins have implicit Agent Owner authority over every Agent in their Organization. They:

• Are not listed under People with access
• Cannot be granted a redundant direct assignment through Share
• Cannot have their Agent authority revoked through Share
• Can recover access settings when another access manager loses authority

Their Organization Role must be changed through Organization membership administration, not Agent sharing.

Agent Creator

Agent Creator records who originally created the Agent. Creation normally grants that person direct Agent Owner access, and the Share dialog labels the assignment with (creator).

Creator identity is immutable provenance, but it is not a permanent authorization source. If the creator’s direct access is changed or removed, the creator label does not independently restore authority.

The creator may still have access through:

• Agent General Access
• A later direct assignment
• Organization Owner or Admin authority

Pending invitees

Pending invitees cannot receive direct Agent Access. They also do not receive Agent General Access until they accept the invitation and become an accepted Organization Member.

If General access is enabled, the role applies automatically after acceptance.

Removed Members

Removing a Membership removes that person’s direct Agent Access.

Removed Members also stop receiving Agent General Access, because they are no longer accepted Members of the Organization.

Custom Agent Access Roles

An Organization may provide custom Agent Access Roles. Custom roles:

• Use the same Agent Permission catalogue
• May grant a nonstandard combination of capabilities
• May not follow the Viewer, Editor, Owner hierarchy
• Take effect according to their current Permission definition
• Must belong to the same Organization when Organization-scoped

Review the role help before assigning one. For General access, the role must include agent.read.

Sharing API

The sharing endpoints operate inside the active Organization context.

{
  "general_access": {
    "role": null
  },
  "assignments": [
    {
      "user_id": "00000000-0000-0000-0000-000000000001",
      "email": "[email protected]",
      "full_name": "Agent Operator",
      "organization_role": "MEMBER",
      "is_pending": false,
      "is_creator": false,
      "access_role": {
        "id": "00000000-0000-0000-0000-000000000002",
        "name": "EDITOR",
        "permissions": [
          "activity.read",
          "agent.lifecycle.manage",
          "agent.read",
          "agent.secret.manage",
          "agent.update",
          "cost.read"
        ],
        "is_locked": true
      }
    }
  ]
}

{
  "general_access_role_id": null,
  "assignments": [
    {
      "user_id": "00000000-0000-0000-0000-000000000001",
      "access_role_id": "00000000-0000-0000-0000-000000000002"
    }
  ]
}

{
  "general_access_role_id": "00000000-0000-0000-0000-000000000003",
  "assignments": [
    {
      "user_id": "00000000-0000-0000-0000-000000000001",
      "access_role_id": "00000000-0000-0000-0000-000000000002"
    }
  ]
}

Security checklist

Before saving:

• Verify the recipient’s email address
• Confirm that the recipient belongs to the correct Organization
• Choose the least-privileged role
• Review whether General access also applies
• Avoid broad Agent Editor access unless every Member should manage configuration and credentials
• Avoid broad Agent Owner access unless every Member should retire and reshare the Agent
• Check whether the change removes your own recovery path
• Remove temporary access after the work is complete
• Review custom-role Permissions rather than trusting the name
• Confirm the result using a non-administrative test Member

Troubleshooting

Next steps

After sharing the Agent:

• Set up Slack
• Review Agent health and logs
• Configure channel access
• Configure an Agent
• Manage the Agent lifecycle