Manage roles and permissions

Understand the authorization model

Agent Barn evaluates three independent sources of authority. Each is resolved separately, and holding one never converts into another.

The diagram shows three separate authority sources side by side. Platform Privilege covers Platform View and platform resources. Organization Role covers Organization-wide governance. Agent Access covers permissions for one specific Agent. Agent Barn evaluates each source on its own; none of the three implies either of the others.

A user may hold more than one source at once. For example:

• A Platform Administrator is not automatically a member of every Organization
• An Organization Member is not automatically able to see every Agent
• An Agent Owner does not become the Organization Owner
• An Organization Admin does hold implicit Agent Owner authority over the Organization’s Agents

Permissions are evaluated from current persisted state on every request. They are not permanently embedded in a session token.

Organization Roles

Every Membership carries exactly one fixed Organization Role: OWNER, ADMIN, or MEMBER. These roles govern Organization-wide actions such as Membership management, shared Templates, custom Skills, Shared Credentials, and Organization settings.

Organization Owner and Agent Owner are different roles. One governs the tenant; the other governs a single Agent.

Organization Role scope

See Manage organizations and members for Membership and ownership workflows.

Agent permissions

Agent Access Roles group individual Agent Permissions. The Default roles column names the locked roles that include each Permission.

Authorization checks use these Permission keys — never a comparison against a role’s display name. A deployment role named “Operator” carries no authority because of its name; its authority comes only from the Permission grants stored for that role.

Locked Agent Access Roles

Agent Barn provides three Agent Access Roles — VIEWER, EDITOR, and OWNER. Their names and Permission grants are locked and cannot be changed.

What each role grants

Agent Viewer grants:

agent.read
activity.read
cost.read

Agent Editor includes the Viewer Permissions and adds:

agent.update
agent.lifecycle.manage
agent.secret.manage

Agent Owner includes the Editor Permissions and adds:

agent.delete
agent.access.manage

Default Agent Access Role matrix

One Membership can hold at most one explicit Agent Access Role for one Agent.

Choose an Agent Access Role

Use the least-privileged role that supports the person’s real work.

Share an Agent directly

Direct access grants one accepted Organization Member one Agent Access Role for one Agent.

1. Open the Agent

Open the Agent you want to share. You need agent.access.manage. Organization Owners, Organization Admins, and existing Agent Owners hold that Permission.

2. Select Share

Select Share from the Agent header or actions. The dialog shows the available Agent Access Roles, the people with direct access, the General Access setting, and your current draft changes.

Organization Owners and Admins are not listed as direct recipients, because they already hold implicit full access.

3. Search for a Member

Use Search Members by name or email. Results may be marked:

• Already has access
• Owner — full access already
• Admin — full access already
• Pending invite
• A role selector and an Add button

Explicit assignments can target accepted Organization Members only. Pending Members cannot receive direct Agent Access until they accept their invitation.

4. Select a role

Choose Viewer, Editor, or Owner. Viewer is the safest default for observation-only access.

5. Add the Member

Select Add. The change stays in the local sharing draft until you save.

6. Save atomically

Review every direct recipient under People with access and the General access setting, then select Save.

Agent Barn applies the entire desired sharing snapshot atomically. If validation fails, none of the draft changes are applied.

Sharing changes take effect on subsequent requests. They do not require the Agent runtime to restart.

Configure General Access

General Access controls whether every accepted Organization Member automatically receives a selected Agent Access Role. Every new Agent defaults to:

Restricted

Configure it

1. Open the Agent’s Share dialog.
2. Find General access.
3. Select Restricted or All Organization Members.
4. If you select all Members, choose Viewer, Editor, or Owner.
5. Review the implications for current and future Members.
6. Select Save.

Understand additive access

Direct access and General Access are positive, additive grants. Effective Permissions are the union of every applicable grant:

• Direct Agent Access Permissions
• +
• General Access Permissions
• Effective Agent Permissions

The diagram reads: the Permissions from a direct Agent Access assignment, plus the Permissions from Agent General Access, combine into the Member’s effective Agent Permissions. The two sources are added together as a union; neither one narrows the other.

Example: direct Viewer and General Editor

• Direct: Agent Viewer
• +
• General: Agent Editor
• Effective Editor-level permissions

The Member holds both Permission sets, so they can operate the Agent as an Editor.

Example: direct Owner and General Viewer

• Direct: Agent Owner
• +
• General: Agent Viewer
• Effective Owner-level permissions

The broader grant wins, because the union never narrows a Permission set. The Member retains Owner-level capabilities.

No deny rules

Agent Barn has no explicit deny role. You cannot assign Viewer directly to reduce access already granted through General Editor — Viewer adds Permissions, and never subtracts them.

To reduce access, change or remove the source granting the broader Permission.

Effective permissions and the interface

Agent read responses include the actions allowed for the current user. The interface uses those effective actions to decide whether to show controls such as Start, Stop, Configure, Manage credentials, Share, and Delete.

Hiding a control is not the security boundary. The API reauthorizes every operation against the current Membership, direct Agent Access, General Access, Agent state, and resource scope. A stale interface may briefly show an outdated control, but the backend still evaluates current persisted authority.

Change or remove access

A user holding agent.access.manage may grant, change, and revoke access — including granting Agent Owner. Every change takes effect on the next request, without an Agent restart.

Change a direct role

1. Open Share.
2. Find the Member under People with access.
3. Select a different role.
4. Select Save.

Remove direct access

1. Open the Member’s role selector.
2. Select Remove access.
3. Select Save.

Removing direct access does not remove access still granted through General Access. The interface warns when removing a direct assignment leaves General Access active.

Remove General Access

1. Open Share.
2. Change General access to Restricted.
3. Select Save.

Removing General Access does not remove a direct assignment. Direct assignments remain unchanged.

Remove all access for a Member

1. Remove their direct assignment.
2. Confirm General Access does not grant the Agent to all Members.
3. If General Access must remain, remove the Membership from the Organization.

Removing the Organization Membership also removes Organization-derived Agent access.

Creator and administrator access

Agent Creator

Creating an Agent grants its creator explicit Agent Owner access.

The Agent Creator field is immutable provenance. Creator identity by itself is not an authorization grant and is not a permanent exception. An authorized access manager can change or remove the creator’s direct assignment when the creator is an ordinary Organization Member.

Organization Owner and Admin

Organization Owners and Admins hold implicit Agent Owner authority over every Agent in the Organization. They:

• Are not offered as direct access recipients
• Are not normally listed under People with access
• Cannot have that implicit authority removed in the Agent sharing dialog

To remove their implicit Agent access, change or remove their Organization Membership through the Organization governance workflow.

Role changes

If an Admin is demoted to Member:

• Their implicit full Agent access ends
• Any preserved direct Agent assignment still applies
• Agent General Access still applies
• Otherwise, the Agent becomes inaccessible to them

Review Agent sharing before demoting administrators.

Current custom-role boundary

The current Agent Barn product exposes the three locked Agent Access Roles — Viewer, Editor, and Owner — for role selection and Agent sharing.

The underlying authorization model can resolve Organization-scoped role records, but the current public UI and API do not expose a complete workflow for creating, editing, or deleting custom Agent Access Roles.

Use the locked roles until custom role management is available through supported product surfaces.

API reference

List available Agent Access Roles

GET /api/v1/organizations/{organization_id}/agents/share-roles

[
  {
    "id": "c7da77aa-bf9c-5626-8bad-5e0ca5159b5d",
    "name": "VIEWER",
    "permissions": [
      "activity.read",
      "agent.read",
      "cost.read"
    ],
    "is_locked": true
  },
  {
    "id": "30e5e846-5e24-548f-a068-2505f774ce35",
    "name": "EDITOR",
    "permissions": [
      "activity.read",
      "agent.lifecycle.manage",
      "agent.read",
      "agent.secret.manage",
      "agent.update",
      "cost.read"
    ],
    "is_locked": true
  },
  {
    "id": "8f2a47ff-7caf-5ded-9027-4a16b85620b3",
    "name": "OWNER",
    "permissions": [
      "activity.read",
      "agent.access.manage",
      "agent.delete",
      "agent.lifecycle.manage",
      "agent.read",
      "agent.secret.manage",
      "agent.update",
      "cost.read"
    ],
    "is_locked": true
  }
]

Read sharing settings

Requires agent.access.manage.

GET /api/v1/organizations/{organization_id}/agents/{agent_id}/share

{
  "general_access": {
    "role": null
  },
  "assignments": [
    {
      "user_id": "018f0000-0000-7000-8000-000000000001",
      "email": "[email protected]",
      "full_name": "Agent Operator",
      "organization_role": "MEMBER",
      "is_pending": false,
      "is_creator": false,
      "access_role": {
        "id": "30e5e846-5e24-548f-a068-2505f774ce35",
        "name": "EDITOR",
        "permissions": [
          "activity.read",
          "agent.lifecycle.manage",
          "agent.read",
          "agent.secret.manage",
          "agent.update",
          "cost.read"
        ],
        "is_locked": true
      }
    }
  ]
}

Replace sharing settings

PUT /api/v1/organizations/{organization_id}/agents/{agent_id}/share
Content-Type: application/json

Restricted, with one direct Editor:

{
  "general_access_role_id": null,
  "assignments": [
    {
      "user_id": "018f0000-0000-7000-8000-000000000001",
      "access_role_id": "30e5e846-5e24-548f-a068-2505f774ce35"
    }
  ]
}

All Organization Members as Viewer, with one direct Editor:

{
  "general_access_role_id": "c7da77aa-bf9c-5626-8bad-5e0ca5159b5d",
  "assignments": [
    {
      "user_id": "018f0000-0000-7000-8000-000000000001",
      "access_role_id": "30e5e846-5e24-548f-a068-2505f774ce35"
    }
  ]
}

Remove every direct assignment and return to Restricted:

{
  "general_access_role_id": null,
  "assignments": []
}

The write is atomic. Invalid recipients, duplicate users, unavailable roles, or other validation errors prevent the complete update.

Agent Secret plaintext is never returned through Agent access, at any role.

Troubleshooting

Security checklist

Next steps

After configuring roles and permissions:

1. Review every Agent Owner assignment.
2. Confirm sensitive Agents use Restricted General Access.
3. Verify Members can reach only the intended Agents.
4. Test the Viewer and Editor boundaries.
5. Review Membership changes for access impact.
6. Continue to Review Agent activity.