Skip to main content
Brainstormer uses a two-tier access control system: platform-level roles for overall platform access and organization-level roles for workspace-specific permissions. On top of these, resource-level permissions provide fine-grained control over individual agents, knowledge bases, and other resources.

​
Platform Roles

Platform roles apply across the entire Brainstormer instance:
The first user to register on a new platform instance is automatically promoted to superadmin. Additional superadmins are configured via the PLATFORM_SUPERADMIN_EMAILS environment variable.

​
Organization Roles

Within each organization, members have one of four roles arranged in a hierarchy:

​
Owner

Full control over the organization. Owners can:
  • Manage all agents, knowledge bases, and conversations
  • Invite and remove members, change roles
  • Manage billing, purchase credits, view invoices
  • Configure organization settings
  • Delete the organization
  • Transfer ownership

​
Admin

Manage the organization day-to-day. Admins can do everything owners can except:
  • Delete the organization
  • Manage billing and purchases
  • Transfer ownership

​
Member

Use resources they have been granted access to. Members can:
  • Use agents they have permission for (chat, view)
  • Access knowledge bases they have permission for
  • View their own conversation history and analytics
  • Upload files and create conversations
Members cannot:
  • Create or edit agents (unless granted explicit permission)
  • Manage members or settings
  • View organization-wide analytics or billing

​
Viewer

Read-only access. Viewers can:
  • View agents and knowledge bases they have explicit access to
  • Read conversations they participated in
Viewers cannot create, edit, or delete anything.

​
Permission Resolution

When you try to perform an action, Brainstormer checks permissions in this order:
1

Superadmin check

If you are a platform superadmin, the action is always allowed — regardless of organization role.
2

Organization role check

Your org role is checked:
  • Owner — All actions within the organization are allowed
  • Admin — All actions except billing management and org deletion
  • Member/Viewer — Proceed to resource-level check
3

Resource permission check

For members and viewers, the system checks for explicit permissions on the specific resource:
  1. Direct user permission — Do you have a permission grant on this specific resource?
  2. Group permission — Are you in any group that has permission on this resource?
  3. Wildcard permission — Is there a permission grant for all resources of this type?
  4. No match — Access denied

​
Resource Types and Actions

Permissions are defined per resource type and action:

​
Example Permission Grants

Here is how permissions work in practice:
  • “Marketing group can use and edit the Sales Bot”: Group “Marketing” gets use and edit actions on the specific agent
  • “Jane can view all knowledge bases”: User Jane gets read and query actions on all knowledge_base resources (wildcard)
  • “Support team can view organization analytics”: Group “Support” gets view_org action on analytics

​
Managing Permissions

Organization owners and admins can manage permissions from Settings > Access:

​
Grant Permission

  1. Select who gets the permission — a user or a group
  2. Select the resource type (agent, knowledge base, etc.)
  3. Select the specific resource (or “all” for wildcard)
  4. Select the actions to grant
  5. Save

​
Revoke Permission

Remove a permission grant to revoke access. The user or group immediately loses the associated actions.
Removing a user from a group also removes all permissions they inherited from that group. Make sure they do not need access through that group before removing them.

​
Default Role Capabilities

Here is a quick reference for what each role can do by default (without additional resource permissions): “Granted” means the member/viewer needs an explicit resource permission to perform the action.

​
Audit Logging

All permission-related actions are recorded in the audit log:
  • Permission grants and revocations
  • Role changes
  • Group membership changes
  • Resource access attempts (both allowed and denied)
The audit log is append-only and cannot be deleted, providing a complete compliance trail.