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

Agent Barn provides three built-in roles for sharing an Agent: Agent Viewer, Agent Editor, and Agent Owner. You can assign these roles through the sharing dialog. Creating, editing, or deleting custom Agent Access Roles is not currently available through the supported interface and API.

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.

How direct access and organization-wide access combine

An Organization Member can receive access in two ways:

• A role assigned directly to that person for the Agent.
• A role granted through the Agent’s All Organization Members setting.

The permissions from both sources apply.

For example, suppose an Agent grants Viewer access to all accepted Organization Members, and Maya also has a direct Editor assignment.

Removing Maya’s direct Editor assignment leaves her with Viewer access through All Organization Members.

Changing the Agent back to Restricted removes the organization-wide grant. It does not remove direct assignments.

Organization Owners and Admins retain their authority over the Agent independently of these sharing settings.

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.

Can I create a custom Agent Access Role?

Custom Agent Access Role management is not currently available through the supported interface and API.

Use the three built-in roles:

These built-in roles cannot be renamed or edited.

The underlying authorization model can represent custom roles, but that does not provide a supported workflow for creating or maintaining them. Do not edit database records to set up a role.

For more about the distinction between Organization Roles and Agent Access Roles, see Manage roles and permissions.

Sharing API

The sharing endpoints operate inside the active Organization context.

{
  "general_access": {
    "role": null
  },
  "assignments": [
    {
      "user_id": "00000000-0000-0000-0000-000000000001",
      "email": "operator@example.com",
      "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
• Confirm the built-in role you selected matches the authority the person needs
• 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