Manage organizations and members

Organization and Membership boundaries

An Organization is the primary ownership and security boundary in Agent Barn. Everything below belongs to exactly one Organization:

Acme Production
├── Memberships
├── Agents
├── Templates
├── Custom Skills
├── Shared Credentials
├── Activity
└── Costs

A user may hold Memberships in several Organizations. Each Membership belongs to exactly one Organization and carries exactly one Organization Role:

[email protected]
├── Membership in Acme Production   (OWNER)
└── Membership in Acme Staging      (MEMBER)

The first diagram lists what a single Organization named Acme Production owns: Memberships, Agents, Templates, Custom Skills, Shared Credentials, Activity, and Costs. The second shows one user, [email protected], holding two separate Memberships — Owner in Acme Production and Member in Acme Staging. The two Organizations hold their own resources and authorization, and neither can reach into the other.

Selecting a different Organization changes the active tenant context. It does not merge data, permissions, Agents, or credentials between Organizations.

Understand the three Organization Roles

Organization Roles govern Organization-wide capability. They are a separate model from Agent Access Roles — Agent Viewer, Agent Editor, Agent Owner, and custom roles — which govern one Agent at a time.

Organization Role matrix

Rows marked Owner only are Organization governance operations that an Admin cannot perform.

Update Organization settings

Organization Owners and Admins can update Organization settings. Depending on the deployed interface, those settings can include the name, the description, allowed models, members, shared Templates, custom Skills, and Shared Credentials.

Renaming an Organization does not change any of the following:

• The Organization ID
• Organization Creator
• The current Owner
• Memberships
• Agent ownership
• API routes

Organization names remain non-unique display labels after a rename.

Manage pending invitations

Resend an invitation

1. Open Members.
2. Find the member marked Pending.
3. Open Member actions.
4. Select Resend invite.
5. Copy the new link if manual delivery is required.

Resending creates a fresh token and immediately invalidates the previous link.

Cancel an invitation

Remove the pending member from the Organization. Removing a pending Membership also revokes its outstanding invitation and set-password links.

Already accepted invitations

Agent Barn rejects a resend for a user who has already accepted their invitation. That user should sign in, or use password recovery instead.

Change a member’s role

Role changes take effect on subsequent requests. Permissions are resolved from current persisted Membership state, rather than being permanently embedded in the user’s access token.

Promote a Member to Admin

Treat this as an Owner-governed operation. An Admin cannot promote a Member to Admin through the role-change lifecycle.

1. Open Members.
2. Open the member’s actions.
3. Select Make admin.
4. Review the access increase.
5. Confirm the change.

The new Admin receives implicit Agent Owner authority over every Agent in the Organization.

Demote an Admin to Member

Only the Organization Owner can demote an Admin. After the demotion:

• The user loses Organization administration
• The user loses implicit authority over every Agent
• Explicit Agent Access and Agent General Access may still provide Agent permissions
• Agents the user created remain Organization-owned
• Their Membership remains active

Review the user’s explicit Agent Access before demoting them, so you know what access will remain.

Owner role changes

The current Owner’s role cannot be changed directly. Transfer ownership instead.

Remove a member

Removing a Membership does not delete the user’s Agent Barn account, and does not delete Organization-owned Agents.

Remove an ordinary Member

An Owner or Admin can remove an ordinary Member.

1. Open Members.
2. Open Member actions.
3. Select Remove from org.
4. Confirm the Organization name and the recipient.
5. Select Remove.

The removed user loses:

• Organization View for that Organization
• Explicit Agent Access tied to the Membership
• Agent General Access
• Access to Organization Templates, Skills, and Shared Credentials
• Organization activity and cost visibility

Agents they created remain owned by the Organization.

Remove an Admin

Only the Owner can remove another Admin. An Admin may remove their own Membership to leave the Organization.

Remove the Owner

The Owner cannot be removed. Transfer ownership first. After the transfer, the previous Owner is an Admin, and can either remove their own Membership or be removed by the new Owner.

Member self-service

Organization Members do not currently have a general self-service leave operation. A Member who wants to leave should ask an Owner or Admin to remove the Membership.

Understand Agent access

Organization Roles and Agent Access Roles answer different questions:

Organization Owner and Organization Admin hold implicit Agent Owner authority over every Agent in the Organization. Organization Members receive Agent permissions through one or more of:

• Creating the Agent, which grants explicit Agent Owner access
• Explicit Agent Access
• Agent General Access

A Member with no applicable Agent Access cannot see that Agent at all.

Changing an Organization Role therefore changes Agent visibility:

• Member to Admin grants implicit authority over every Agent
• Admin to Member removes that implicit authority
• Explicit Agent Access and Agent General Access may remain after a demotion
• Removing the Membership removes all Organization-derived Agent access

See Manage roles and permissions for the complete Agent Access model.

Switch Organizations safely

The Organization selector is built only from the user’s real Memberships. When you switch Organizations:

• The active Organization ID changes
• Organization-scoped routes use the new ID
• Known Organization-scoped interface caches are cleared
• Agent, Template, Skill, credential, activity, and cost views reload
• Permissions are recalculated for the selected Membership

Agent Barn has no default or primary Organization that silently grants access. Platform View is separate, and has no active Organization.

Platform Administrator boundaries

Platform Privilege and Organization Membership are independent. Platform Privilege is not an Organization Membership.

Platform View does not provide unrestricted access to:

• Agent conversations
• Prompts or Templates
• Skill content
• Credentials or Secrets
• Runtime logs
• Raw telemetry
• Organization configuration payloads

API reference

Create an Organization

POST /api/v1/organizations
Content-Type: application/json

{
  "name": "Acme Production",
  "description": "Production customer-support Agents"
}

{
  "id": "018f0000-0000-7000-8000-000000000001",
  "created_at": "2026-08-29T10:00:00Z",
  "updated_at": "2026-08-29T10:00:00Z",
  "name": "Acme Production",
  "description": "Production customer-support Agents",
  "owner_email": "[email protected]",
  "owner_name": "Organization Owner",
  "allowed_models": [
    "z-ai/glm-5.2"
  ]
}

Read Organization details

GET /api/v1/organizations/{organization_id}

Update Organization settings

PATCH /api/v1/organizations/{organization_id}
Content-Type: application/json

{
  "name": "Acme AI Operations",
  "description": "Production Agent operations"
}

List members

GET /api/v1/organizations/{organization_id}/members

Optional filters:

search=alice
limit=50

An example member:

{
  "user_id": "018f0000-0000-7000-8000-000000000002",
  "email": "[email protected]",
  "full_name": "Alice Example",
  "role": "MEMBER",
  "is_pending": false
}

Invite a member

POST /api/v1/organizations/{organization_id}/members
Content-Type: application/json

{
  "email": "[email protected]",
  "full_name": "New Member",
  "role": "MEMBER"
}

A new user receives a response containing an invitation link:

{
  "member": {
    "user_id": "018f0000-0000-7000-8000-000000000003",
    "email": "[email protected]",
    "full_name": "New Member",
    "role": "MEMBER",
    "is_pending": true
  },
  "invite_link": "https://app.example.com/set-password?token=REDACTED"
}

For an existing active user, invite_link is null.

Resend an invitation

POST /api/v1/organizations/{organization_id}/members/{user_id}/resend-invite

{
  "invite_link": "https://app.example.com/set-password?token=REDACTED"
}

The previous link becomes invalid.

Change a member’s role

PATCH /api/v1/organizations/{organization_id}/members/{user_id}
Content-Type: application/json

{
  "role": "ADMIN"
}

Do not assign OWNER through this endpoint. Use ownership transfer.

Transfer ownership

POST /api/v1/organizations/{organization_id}/transfer-ownership
Content-Type: application/json

{
  "user_id": "018f0000-0000-7000-8000-000000000004"
}

A successful transfer returns HTTP 204.

Remove a member

DELETE /api/v1/organizations/{organization_id}/members/{user_id}

A successful removal returns HTTP 204.

Delete an Organization

DELETE /api/v1/organizations/{organization_id}

The Owner must make sure no non-deleted Agents remain.

Troubleshooting

Security checklist

Next steps

After configuring the Organization and its Memberships:

1. Review every Admin assignment.
2. Remove expired or abandoned pending invitations.
3. Configure Agent-specific access for Members.
4. Review Shared Credentials and provider identities.
5. Document the Owner and the recovery process.
6. Continue to Manage roles and permissions.