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:

alice@example.com
├── 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, alice@example.com, 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, members, shared Templates, custom Skills, Shared Credentials, and the Organization-wide Agent Settings surface.

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.

Govern Organization Agent Settings

Open /dashboard/{org_id}/settings?tab=agents after selecting the Organization. This is an Organization-wide settings surface, not the configuration page for one Agent.

The Agents section shows the default model, its source, counts of inheriting and overridden Agents, allowed models, and an Organization model map. Reading or changing it requires organization.update.

Agent Access controls a particular Agent; Organization Permissions control Organization-wide settings. Agent Owner or Agent Editor access alone does not allow someone to change the Organization default or its allowlist.

Separate model governance concepts

effective_default_model(organization)
  = organization Agent Settings default
  or platform default

effective_model(agent)
  = Agent model override
  or effective_default_model(organization)

An Agent Settings row is created lazily on its first write. A missing row and an all-null row both mean the Organization follows the platform default, which is resolved rather than copied into every Agent.

An explicit null update clears an Organization-owned choice and resumes following the platform default. Omitting default_model from an update leaves its current stored value unchanged.

Manage the allowed-model policy

The Organization's allowed_models determines what it may explicitly select for an Organization-owned default or Agent-specific override; it is not the effective default itself.

Allowed models
├── model-a
├── model-b
└── model-c

Organization default
└── model-b

Agent A
└── inherits model-b

Agent B
└── explicitly overrides with model-c

Publishing or adding an allowed model does not change the default automatically. An Organization-owned default must remain allowed: selecting one outside the allowlist is rejected, and removing the active Organization-owned default is rejected until it is changed or cleared. Explicit Agent overrides must also remain allowed; an attempted removal identifies the affected Agents so an administrator can repin them or return them to inheritance first.

When an Organization follows the platform default, that platform-controlled value may be outside the Organization's allowlist and can change during deployment. Inheriting Agents do not block removal of that model from the allowlist, but explicit overrides and an Organization-owned default remain subject to the policy.

Allowed entries can be exact model identifiers or supported glob patterns. New entries are checked against the current OpenRouter catalogue when available; a temporary catalogue failure does not erase existing policy. Models no longer present in the catalogue can remain as orphaned entries until an administrator removes them. An Organization-owned default must resolve to one concrete selectable model.

Review change impact and audit history

The inheriting and override counts include all non-deleted Agents in the Organization. They show the scope of a policy change without revealing inaccessible Agent identities.

• Changing the Organization default affects what inheriting Agents use at their next start; it does not write a model into every Agent, restart running Agents, or affect explicit overrides.
• For a running Agent, running_model is the current Runtime value, effective_model is what would be selected now, and pending_model appears when they differ.
• An inheriting Agent keeps its running model until its next start or an explicit restart. Do not restart an Agent with an explicit override solely because the Organization default changed.

A changed default emits organization.agent_settings.changed through the Domain Event and security-audit path. A changed allowlist is a separate Organization update and emits organization.model_allowlist.changed. Saving the same value creates no event; these are distinct audit facts, not Communications journal entries.

Governance workflow

1. Confirm that the user is an Organization Owner or Admin.
2. Open Settings and select Agents.
3. Review the effective default, its source, and the inheriting and override counts.
4. Add an allowed model if necessary, then select an Organization-owned default or continue following the platform.
5. Review the confirmation: inheriting Agents adopt the value after restart, while overridden Agents are unaffected.
6. Restart only the Agents that should adopt the changed effective model immediately, then review Organization audit history when needed.

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": "owner@example.com",
  "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"
}

Read or update Agent Settings

GET /api/v1/organizations/{organization_id}/agent-settings
PUT /api/v1/organizations/{organization_id}/agent-settings

A read response describes the resolved default and its current blast radius:

{
  "default_model": null,
  "effective_default_model": "<resolved-model>",
  "default_model_source": "platform",
  "inheriting_agent_count": 3,
  "override_agent_count": 1,
  "updated_at": null
}

To select an Organization-owned default, send:

{
  "default_model": "<allowed-model>"
}

To resume following the platform default, send:

{
  "default_model": null
}

Update allowed models

Allowed models remain part of the Organization update contract, not the Agent Settings update body.

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

{
  "allowed_models": [
    "<model-or-pattern>"
  ]
}

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": "alice@example.com",
  "full_name": "Alice Example",
  "role": "MEMBER",
  "is_pending": false
}

Invite a member

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

{
  "email": "new-member@example.com",
  "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": "new-member@example.com",
    "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.