--- title: Share access to an Agent canonical: "https://agentbarn.dev/guides/agents/sharing" pubDate: "2026-08-29T00:00:00.000Z" updatedDate: "2026-09-13T13:41:42.000Z" author: Agent Barn description: "Share Agent Access through direct Member assignments or Agent General Access for the Agent and its subordinate Connections, Conversations, Tool Calls, Secrets, Skills, configuration, logs, and costs." tags: [Agents, How-to, "Agent owners, access managers, Organization administrators, and security reviewers", share Agent, Agent Access, Agent Access Role, Agent Viewer, Agent Editor, Agent Owner, General access, Restricted Agent, direct access, Organization Members, manage Agent access, remove Agent access] categories: [Guides, Agents] --- Sharing controls which Organization Members can find, inspect, operate, configure, or administer an Agent inside Agent Barn. Agent Barn supports direct access for selected Members, and Agent General Access for all accepted Organization Members. These grants are additive: a Member receives the combined Permissions available from every applicable access source. ## Overview An Agent remains owned by its Organization. Sharing grants authority over that Agent; it does not transfer ownership of the underlying resource. | Access source | Audience | Scope | | --- | --- | --- | | Direct Agent Access | One accepted Organization Member | One Agent Access Role on one Agent | | Agent General Access | All current and future accepted Organization Members | One Agent Access Role on one Agent | | Implicit Organization authority | Organization Owner and Organization Admin | Full authority over every Agent in the Organization | 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. **Important** Agent Barn access and communication-platform access are separate. Sharing an Agent does not add someone to a Slack channel, Telegram group chat, or Discord server, and it does not bypass the Agent’s [channel-access policy](/guides/agents/channel-access). ## Compare Agent Access Roles Every Organization includes three locked Agent Access Roles. | Role | Capabilities | | --- | --- | | **Agent Viewer** | View the Agent, Conversations, Tool Calls, activity, Logs, and Agent-specific costs | | **Agent Editor** | Viewer capabilities, plus configuration, lifecycle, Skill assignment, and Agent Secret management | | **Agent Owner** | Editor capabilities, plus Agent retirement and access management | 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 **Warning** Agent Owner can retire the Agent and change who controls it. Grant this role only when the recipient should have full administrative authority over the Agent. 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. **Important** Platform participation and Agent Barn sharing are separate controls. An Agent Access Role decides what someone can do with the Agent inside Agent Barn. The Agent’s channel-access policy decides where the Agent itself may participate, and who may talk to it on Slack, Telegram, or Discord. ## Open Share 1. Select the Organization that owns the Agent. 2. Open the Agent from **Home**. 3. Select **Share** in the Agent header. **\[Agent name\]** Runtime · platform · condition Configuration Share The Share dialog is titled: ``` Share [Agent name] Manage who can access this Agent, directly or through General access. ``` The dialog contains: - A Member search - A role-help action - **People with access** - **General access** - **Cancel** - **Save** Changes remain local to the dialog until you select **Save**. Organization Owners and Organization Admins are not included under **People with access**, because their full access is implicit and cannot be revoked through Agent sharing. ## Review available roles Select the help icon in the Share dialog to open **Agent Access Roles**. **? Agent Access Roles** Viewer: View, See activity, See costs Editor: View, Edit, Start/stop, Manage secrets, See activity, See costs Owner: View, Edit, Start/stop, Manage secrets, Delete, Manage access, See activity, See costs The role legend lists the Permissions currently attached to each available role. Roles containing sensitive Permissions display an additional warning. In particular, look for roles that can: - Delete the Agent - Manage who has access to the Agent Use the least-privileged role that supports the recipient’s responsibilities. | Responsibility | Recommended locked role | | --- | --- | | Observe and diagnose | Agent Viewer | | Configure and operate | Agent Editor | | Retire and manage access | Agent Owner | These three built-in roles are the only roles you can select. They cannot be renamed or edited. ## Grant direct access Direct access grants one Agent Access Role to one accepted Organization Member for this Agent. ### Find the Member In the Share dialog: 1. Search by the Member’s name or email address. 2. Find the intended Member in the results. 3. Review their email carefully. 4. Select the Agent Access Role. 5. Select **Add**. **Agent Operator** operator@example.com Viewer Add The Member appears under **People with access**, but the grant is not active until you select **Save**. A search result may show one of these conditions: | Condition | Meaning | | --- | --- | | Role selector and **Add** | The Member can receive direct access | | Already has access | The Member is already in the local assignment list | | Owner: full access already | The Organization Owner already has implicit full authority | | Admin: full access already | The Organization Admin already has implicit full authority | | Pending invite | The invitation must be accepted first | **Note** Pending invitees cannot receive direct Agent Access. After they accept the Organization invitation, search for them again and add the direct grant. Only accepted Members of the same Organization are eligible. Users from another Organization cannot be granted access to this Agent. ### Direct-assignment rules - One Member can have at most one direct Agent Access Role for an Agent. - The same Member can have different roles on different Agents. - Direct access applies only to the selected Agent. - Changing an Organization Role does not automatically create a direct Agent assignment. - Removing the Member’s Organization Membership removes their direct Agent Access. ## Configure General access Agent General Access defines whether accepted Organization Members automatically receive access to this Agent. Choose one of two modes. ### Restricted No Organization-wide Agent Access Role is granted. Access is limited to: - Directly assigned Members - Organization Owners - Organization Admins Restricted is the default for new Agents. It does not remove direct assignments, and it does not affect the implicit authority of the Organization Owner or Organization Admin. ### All Organization Members Every current and future accepted Organization Member receives the selected Agent Access Role. The grant applies dynamically to: - Current accepted Organization Members - Members who accept an invitation later - Future Members added to the Organization It does not apply to pending invitees, removed Members, or users outside the Organization. The selected role must include permission to read the Agent. ### Choose a safe General Access role | General Access role | Effect | | --- | --- | | **Agent Viewer** | Every accepted Member can find and inspect the Agent | | **Agent Editor** | Every accepted Member can configure, start, Pause, and manage credentials for the Agent | | **Agent Owner** | Every accepted Member can retire the Agent and manage its sharing | **Security** Agent Viewer is usually the safest role for Organization-wide visibility. Use Organization-wide Editor or Owner access only when every current and future accepted Member should receive those operational or administrative Permissions automatically. Changing the General Access role affects the next request made by each applicable Member. It does not create a separate direct assignment for every Member. ## Change or remove access Existing direct assignments appear under **People with access**. **Agent Operator (creator)** operator@example.com Editor Remove access ### Change a direct role 1. Find the Member. 2. Open their role selector. 3. Select the new Agent Access Role. 4. Review other pending changes. 5. Select **Save**. A role change replaces that Member’s direct role for this Agent. If Agent General Access also applies, the Member continues to receive the union of the direct and General Access Permissions. ### Remove direct access 1. Find the Member. 2. Open their role selector. 3. Select **Remove access**. 4. Select **Save**. If General access is **All Organization Members**, removing a direct assignment does not remove all of the Member’s access. The interface warns that the Member still has the General Access role. **Important** To remove a Member’s effective access completely, remove their direct assignment and make sure they receive no applicable Agent General Access. Organization Owners and Organization Admins still retain implicit full authority. ### Remove General access Set **General access** to **Restricted**, then select **Save**. This removes the Organization-wide grant but preserves every direct assignment. ### Change the General Access role Keep **All Organization Members** selected and choose a different role. The new General Access role applies to current and future accepted Members after the change is saved. ### Removing your own access A user with `agent.access.manage` may be able to remove or reduce the direct grant that currently authorizes them. Review your remaining General Access or Organization authority first. After the save, you may lose the ability to reopen the Agent or correct its sharing settings. Organization Owners and Organization Admins retain implicit recovery authority. ## Save and verify The Share dialog saves the complete desired sharing state. 1. **Local sharing draft** Additions, role changes, and removals stay in the dialog 2. **Save** The dialog sends General access and the complete direct-assignment list 3. **One atomic access snapshot** Every change applies together, or none of them applies Selecting **Save** sends: - The selected General Access role, or Restricted - The complete list of direct Member assignments - The selected Agent Access Role for each assignment The update is atomic. If saving fails, none of the sharing changes are applied, and the local draft remains available in the dialog. After a successful save, Agent Barn displays **Sharing updated.** ### Verify direct access Ask the recipient to: 1. Refresh Agent Barn. 2. Select the correct Organization. 3. Confirm that the Agent appears on **Home**. 4. Open the Agent. 5. Confirm that controls match the intended role. | Role | Expected controls | | --- | --- | | Agent Viewer | Read-only Agent and activity views | | Agent Editor | Configuration and lifecycle controls, without Share or retirement | | Agent Owner | Configuration, lifecycle, Share, and retirement controls | ### Verify Restricted access Use an accepted Organization Member who has no direct assignment, and no Organization Owner or Admin authority. They should not be able to find or open the Agent. Inaccessible Agents are concealed as not found, rather than revealing that the resource exists. ### Verify General access Use an accepted Organization Member without a direct assignment. They should be able to find the Agent and receive the controls associated with the selected General Access role. ## How additive Permissions work Direct Agent Access and Agent General Access are both positive grants. | General access | Direct access | Effective result | | --- | --- | --- | | Restricted | Agent Viewer | Viewer Permissions | | Agent Viewer | None | Viewer Permissions | | Agent Viewer | Agent Editor | Combined Permissions equivalent to Editor | | Agent Editor | Agent Viewer | Editor Permissions remain; Viewer does not reduce them | | Agent Viewer | Agent Owner | Owner Permissions | | Agent Editor | Direct assignment removed | Editor Permissions remain through General access | | Restricted | Direct assignment removed | No access for an ordinary Organization Member | ### 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. | Access source | Maya’s access | | --- | --- | | All Organization Members | Viewer | | Direct assignment | Editor | | Effective access | Editor | 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: | Role | What the person can do | | --- | --- | | Agent Viewer | View the Agent, its activity and logs, and its costs. | | Agent Editor | Do everything a Viewer can do, plus change configuration, start or pause the Agent, manage assigned Skills, and manage its credentials. | | Agent Owner | Do everything an Editor can do, plus retire the Agent and manage who has access. | 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](/guides/observe-and-govern/roles-and-permissions). ## Sharing API The sharing endpoints operate inside the active Organization context. | Method and endpoint | Purpose | Required authority | | --- | --- | --- | | `GET /agents/share-roles` | List Agent Access Roles available to the Organization | Active Organization Membership | | `GET /agents/{agent_id}/share` | Read the Agent’s General access and direct assignments | `agent.access.manage` | | `PUT /agents/{agent_id}/share` | Atomically replace the complete sharing snapshot | `agent.access.manage` | | `GET /organizations/{organization_id}/members?search=...` | Search Organization Members for direct assignment | Applicable Organization and Agent authority | `` ### Read the sharing snapshot A sharing response contains General access and direct assignments: ``` { "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 } } ] } ``` A `null` General access role means Restricted. ### Replace the complete snapshot To keep General access Restricted and grant one direct role: ``` { "general_access_role_id": null, "assignments": [ { "user_id": "00000000-0000-0000-0000-000000000001", "access_role_id": "00000000-0000-0000-0000-000000000002" } ] } ``` To enable General access, provide its role ID: ``` { "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" } ] } ``` **Important** `PUT /agents/{agent_id}/share` is a complete replacement, not a partial patch. Omitting an existing visible assignment from `assignments` removes that direct grant. Each user may appear only once in the assignment list. Every assignment must reference an accepted ordinary Member of the same Organization, and an Agent Access Role available to that Organization. `` ## Security checklist **Security** Agent sharing can expose Conversations, Tool Calls, Logs, costs, configuration, credential metadata, and operational controls. Treat access changes as security-sensitive changes. 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 ### The Share action is missing Your effective Permissions do not include `agent.access.manage`. Agent Owner includes this Permission. Organization Owners and Organization Admins also have implicit full authority. Ask an existing access manager to review your role. ### The Member does not appear in search Confirm that: - The user has been invited to the same Organization - You are working in the correct active Organization - The name or email search is correct - The Organization Membership has not been removed - The search is specific enough The dialog displays the first matching results. Refine broad searches to find additional Members. ### The Member appears as Pending invite The user must accept the Organization invitation before receiving direct Agent Access. After acceptance, search again and add them. If General access is enabled, it begins applying automatically after their Membership is accepted. ### The Organization Owner or Admin cannot be added This is expected. Organization Owners and Organization Admins already have implicit full authority over every Agent in the Organization. They are not represented as revocable direct assignments. ### Removing direct access did not remove the Agent The Member may still have access through Agent General Access. Review **General access** and the selected role. Direct and General Access Permissions are additive. The Member may also be an Organization Owner or Organization Admin. ### Selecting a lower direct role did not reduce access A lower direct role cannot subtract Permissions granted through General access. For example, direct Agent Viewer does not reduce General Agent Editor authority. Change or remove the broader General access grant if the Member should lose those Permissions. ### A Member still sees controls from their previous role Access changes take effect on the next request. Ask the Member to refresh the Agent page and confirm that they are using the correct active Organization. If the controls remain, review every applicable access source. ### Saving reports that the Member is unavailable The Membership may have changed after the Share dialog was opened. The Member may have: - Been removed - Changed to Organization Owner or Admin - Become unavailable in the active Organization Reload the Share dialog and review the current Organization Membership. ### A sharing change is rejected The available people or roles may have changed since you opened the dialog. Reopen the sharing dialog and review the current options. Confirm that the person has accepted membership in the same Organization and that the selected role is available. If you are using the API, fetch the current sharing state and role catalogue before preparing another request. Use a role ID returned by the catalogue rather than inventing one. Saving through the sharing endpoint replaces the complete sharing snapshot. Include the assignments you intend to keep. ### General access role is rejected The selected role must include `agent.read`. Choose a role that permits Members to open the Agent. ### Saving fails after several edits The sharing update is atomic. A failure means none of the draft changes were applied. Keep the dialog open, correct the reported problem, and save again. If the underlying Membership or role changed, reload the sharing settings before retrying. ### You removed your own access If General access still applies, you retain the Permissions from that role. Otherwise, ask an Organization Owner, Organization Admin, or another Agent access manager to restore a direct assignment. ## Next steps After sharing the Agent: - [Set up Slack](/guides/platforms/slack) - [Review Agent health and logs](/guides/agents/health-and-logs) - [Configure channel access](/guides/agents/channel-access) - [Configure an Agent](/guides/agents/configuration) - [Manage the Agent lifecycle](/guides/agents/lifecycle)