> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brainstormer.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Roles and Permissions

> Understand the role hierarchy, resource permissions, and access control system.

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:

| Role           | Access                                                                                                                                     |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Superadmin** | Full access to everything across all organizations. Can manage platform configuration, view all billing data, and access admin dashboards. |
| **User**       | Standard access. Can only interact with organizations they belong to.                                                                      |

<Info>
  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.
</Info>

## 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:

<Steps>
  <Step title="Superadmin check">
    If you are a platform superadmin, the action is always allowed — regardless of organization role.
  </Step>

  <Step title="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
  </Step>

  <Step title="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
  </Step>
</Steps>

## Resource Types and Actions

Permissions are defined per resource type and action:

| Resource Type      | Available Actions                                                |
| ------------------ | ---------------------------------------------------------------- |
| **Agent**          | `use`, `edit`, `delete`, `view_analytics`, `manage_distribution` |
| **Knowledge Base** | `read`, `add_sources`, `edit`, `delete`, `query`                 |
| **Analytics**      | `view_own`, `view_org`, `export`                                 |
| **Billing**        | `view`, `manage`, `purchase_credits`                             |
| **Settings**       | `view`, `edit`                                                   |
| **Members**        | `view`, `invite`, `remove`, `change_role`                        |
| **Groups**         | `view`, `create`, `edit`, `delete`, `manage_members`             |
| **API Keys**       | `view`, `create`, `revoke`                                       |
| **Conversations**  | `view_own`, `view_all`, `delete`                                 |

### 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.

<Warning>
  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.
</Warning>

## Default Role Capabilities

Here is a quick reference for what each role can do by default (without additional resource permissions):

| Capability             | Owner | Admin | Member  | Viewer  |
| ---------------------- | ----- | ----- | ------- | ------- |
| Create agents          | Yes   | Yes   | No      | No      |
| Edit any agent         | Yes   | Yes   | No      | No      |
| Delete agents          | Yes   | Yes   | No      | No      |
| Chat with agents       | Yes   | Yes   | Granted | Granted |
| Create knowledge bases | Yes   | Yes   | No      | No      |
| Upload documents       | Yes   | Yes   | Granted | No      |
| View org analytics     | Yes   | Yes   | No      | No      |
| View own analytics     | Yes   | Yes   | Yes     | Granted |
| Manage members         | Yes   | Yes   | No      | No      |
| Manage billing         | Yes   | No    | No      | No      |
| Manage settings        | Yes   | Yes   | No      | No      |
| Delete organization    | Yes   | No    | No      | No      |

"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.