Roles and Permissions
botBrains uses a two-tier role system to give you precise control over who can access, view, and modify you AI agent projects. Whether you’re a small team or an enterprise organization, you can grant exactly the right level of access to each team member while maintaining security and preventing unauthorized changes.Why Role-Based Access Matters
Proper access control protects your AI operations while enabling collaboration:Protect Sensitive Data
Customer conversations, knowledge bases, and configuration settings often contain sensitive business information. Role-based permissions ensure only authorized team members can access customer data, view conversation history, or export user information.Prevent Accidental Changes
Your AI’s knowledge and guidance directly impacts customer experience. Restricting who can modify deployments, edit knowledge sources, or change AI behavior prevents well-meaning team members from accidentally breaking production systems.Enable Safe Collaboration
Team members need different levels of access based on their responsibilities. Support analysts need to view conversations but shouldn’t change AI configuration. Developers need full control in development projects but should have limited access to production.Meet Compliance Requirements
Enterprise customers often need to demonstrate access controls for SOC 2, ISO 27001, or industry-specific compliance. Role-based permissions provide the audit trail and access restrictions compliance frameworks require.Scale Your Team Efficiently
As your organization grows, managing individual permissions becomes impossible. Roles let you assign consistent access levels across team members, making it easy to onboard new people and adjust access as responsibilities change.Understanding the Two-Tier System
botBrains uses both Organization Roles and Project Roles to provide flexibility while maintaining security. Every team member has one organization role and can have different project roles across your projects.Organization vs. Project Roles
Think of organization roles as your baseline access level and project roles as specific permissions for individua AI agents: Organization Roles define access across your entire botBrains account:- Apply to all projects by default
- Control administrative capabilities like billing and team management
- Cannot be customized - use built-in roles only
- Best practice: Assign most team members Organization Member
- Only apply within a single project
- Can be customized with granular permissions
- Override organization-level access (if more restrictive)
- Enable per-project access control
Permission Priority: A user’s effective permissions are the union of their organization role and project role. If either role grants a permission, the user has that access. This means organization roles set a baseline that project roles cannot remove.
How Permissions Combine
When a team member tries to perform an action, botBrains checks both their organization role and their project role:- Sarah has Organization Admin (can manage all projects)
- Sarah has Project Viewer in Production project (can only view)
- Result: Sarah can still modify Production because Organization Admin grants broader permissions
Organization Roles
Organization roles cannot be customized - you must use one of the three built-in roles. Each organization member has exactly one organization role.Organization Owner (o_owner)
The highest level of access with complete control over the organization. Who Needs This:- Company executives or business owners
- Primary account administrators
- Billing and subscription managers
- Full access to all projects (create, read, update, delete)
- Manage organization settings and billing
- Invite and remove team members
- Assign organization and project roles
- Create and configure new projects
- Access all conversations and analytics across projects
- Generate and manage API keys
- Configure integrations and deployments
- Transfer organization ownership (must contact support)
- Be removed from the organization (inherent account owner)
Organization Admin (o_admin)
Administrative access with full project management capabilities but limited organization-level controls. Who Needs This:- Technical leads and project managers
- Senior engineers responsible for AI configuration
- Team members who need access across multiple projects
- Full access to all projects (create, read, update, delete)
- Create new projects
- Configure knowledge, guidance, and deployments
- View and analyze all conversations
- Manage integrations and API keys
- View team members and their roles
- Manage project-level access
- Modify organization billing or subscription
- Remove team members from organization (only Organization Owner can)
- Change organization-level settings
- Assign organization roles to other users
Organization Member (o_member)
Minimal organization-level permissions. This is the recommended default role for most team members. Who Needs This:- Most of your team members (90%+ of users)
- Anyone who only needs access to specific projects
- Users whose access should be controlled per-project
- Access projects where they have been assigned a project role
- View their own profile and preferences
- Accept invitations to projects
- See projects they haven’t been assigned to
- Create new projects
- View organization-wide settings or billing
- Manage other team members
- Access organization-level analytics
Need help choosing the right role? The Team Settings page includes a “Which Role should I choose?” link that provides role selection guidance based on common use cases.
Project Roles
Project roles control access to individua AI agent projects. botBrains provides four built-in project roles, and you can create unlimited custom roles with specific permission combinations.Built-In Project Roles
Project Owner (p_owner)
Complete control over a specific project. Who Needs This:- Project leads responsible for a specifi AI agent
- Teams who “own” a particular product or brand
- Users who need full administrative access to one project but not others
- Create, read, update, and delete all project resources
- Manage knowledge sources, guidance, and deployments
- Configure integrations and frames
- View and manage all conversations
- Manage project team members and roles
- Create custom roles (unique to Project Owner)
- Delete the project entirely
Project Admin (p_admin)
Full project access except for critical destructive operations. Who Needs This:- Senior team members who configure and maintain the AI
- Developers who deploy changes to production
- Team leads who need full access but shouldn’t delete the project
- Read and update all project configuration
- Manage knowledge, guidance, and deployments
- Create and manage integrations
- View all conversations and analytics
- Manage topics and labels
- Generate API keys
- Invite project team members
- Delete the project
- Create custom roles
- Remove Project Owners
Project Member (p_member)
Read and write access to most features without administrative capabilities. Who Needs This:- Support team members who update knowledge
- Content creators who maintain documentation snippets
- Team members who monitor conversations and make improvements
- Read all project configuration
- Create and update knowledge sources (snippets, tables)
- View and label conversations
- View analytics and metrics
- Update guidance instructions
- Create and update deployments
- Delete deployments
- Delete knowledge sources
- Manage team access
- Generate API keys
- Delete conversations
- Modify project settings
Project Viewer (p_viewer)
Read-only access to view project data without making changes. Who Needs This:- Stakeholders who need visibility into AI performance
- Quality assurance reviewers
- Team members who monitor but don’t configure
- External consultants reviewing your setup
- View project configuration
- Read knowledge sources
- View conversations and analytics
- Access metrics and topics
- View deployment settings
- View guidance profiles
- Modify any project settings
- Create or update knowledge
- Change deployments
- Label conversations
- Generate API keys
- Export data
Custom Project Roles
Create custom roles with precise permission combinations tailored to your team’s workflow.Why Create Custom Roles
Built-in roles cover common scenarios, but your organization may have unique needs:- Specialized Team Functions - QA teams who can label conversations but not edit knowledge
- Contractor Access - Limited permissions for external consultants
- Compliance Requirements - Roles that separate conversation access from configuration access
- Development Workflows - Different permissions in dev, staging, and production projects
Creating a Custom Role
Navigate to your project’s Team settings and follow these steps:1
Access Roles Tab
Go to Project → Settings → Team → Roles tab
2
Create New Role
Click Add Role button to open the role creation dialog
3
Name and Describe
Enter a clear role name (e.g., “QA Reviewer”) and description explaining its purpose
4
Select Permissions
Choose specific permissions grouped by functional area (see permission categories below)
5
Save and Assign
Save the role and assign it to team members who need this access level
Permission Categories
Permissions are organized into logical groups. When selecting permissions for custom roles, consider what each category enables: Knowledge Management- knowledge:read - View all knowledge sources (data providers, snippets, tables)
- knowledge:write - Create, update, and delete knowledge sources
- guidance:read - View AI behavior instructions and profiles
- guidance:write - Modify guidance rules and create new profiles
- conversation:read - View conversation history and messages
- conversation:write - Label conversations and add internal notes
- conversation:generate - Test AI responses in sandbox mode
- deployment:read - View deployment configurations
- deployment:create - Create new deployments
- deployment:update - Modify existing deployments
- deployment:delete - Remove deployments
- metric:read - Access analytics dashboards and performance metrics
- topic:read - View topic clusters and trends
- topic:write - Manage custom topics and categories
- label:read - See conversation labels
- label:upsert - Create and apply labels
- label:delete - Remove labels
- zendesk:install - Connect Zendesk integration
- zendesk:read - View Zendesk settings
- zendesk:update - Modify Zendesk configuration
- zendesk:import - Import historical tickets
- salesforce:install - Connect Salesforce integration
- salesforce:read - View Salesforce settings
- salesforce:update - Modify Salesforce configuration
- slack:install - Connect Slack integration
- slack:read - View Slack settings
- slack:update - Modify Slack configuration
- frame:read - View website widget configurations
- frame:create - Create new widget instances
- frame:update - Modify widget appearance and behavior
- frame:delete - Remove widgets
- table:read - View custom data tables
- table:write - Create and modify data tables
- file:read - Access uploaded files
- userpool:read - View user lists and profiles
- userpool:create - Create new user pools
- userpool:update - Modify user information
- userpool:delete - Remove user pools
- role:read - View roles and permissions
- role:write - Create and modify custom roles
- role:assign - Assign roles to team members
- invitation:read - View pending invitations
- invitation:write - Invite new team members
- project_apikey:read - View API keys (masked)
- project_apikey:write - Generate and revoke API keys
- trigger:read - View automation triggers
- trigger:write - Create and modify triggers
- export:read - Export conversation data (limited)
- full_export:read - Export all data including PII
- project:read - View project settings
- project:update - Modify project configuration
- project:delete - Delete the project
- billing:read - View project usage and billing
- evaluation:read - View test suite results
- evaluation:write - Create and run test suites
Permission Dependencies: Some permissions automatically require others. For example, granting
deployment:update automatically includes deployment:read. The UI handles these dependencies automatically when creating custom roles.Example Custom Roles
Quality Assurance ReviewerManaging Team Access
Inviting Team Members
Add new people to your organization or specific projects:1
Navigate to Team Settings
Go to Organization → Settings → Team or Project → Settings → Team
2
Send Invitation
Click Invite User and enter email addresses (one per line for multiple invites)
3
Assign Role
Select the appropriate organization or project role for the new team member
4
Send and Track
Send invitations and track acceptance in the Invitations tab
- Invited user receives email with join link
- User creates botBrains account or signs in
- User automatically joins organization with assigned role
- User appears in Members list with full access
- View all pending invitations in the Invitations tab
- Resend invitation emails if needed
- Revoke invitations before they’re accepted
- Track invitation expiration dates
Changing User Roles
Adjust access levels as team members’ responsibilities change: From Team Members List:- Navigate to Settings → Team → Members tab
- Find the user in the members table
- Click the role dropdown in their row
- Select the new role
- Organization-level Team page (
/settings/team) shows organization roles for all members - Project-level Team page (
/project/settings/team) shows both project roles AND organization roles - When viewing a project’s team page, you’ll see a column for “Organization Role” to understand the complete access picture
- Use the “Go to Organization Roles” / “Go to Project Roles” buttons to quickly navigate between levels
- User’s access updates in real-time
- Active sessions continue but new actions use updated permissions
- User may see UI elements appear or disappear based on new role
Permission Inheritance Warning
botBrains warns you when organization roles override project restrictions: Scenario: You assign a user Project Viewer role (read-only) but they have Organization Admin (full access). What Happens:- A warning dialog appears explaining the conflict
- Shows which permissions the user retains through their organization role
- Recommends demoting to Organization Member for true project-level control
- You can proceed or cancel to reconsider the role assignment
Removing Team Members
Remove users from your organization or specific projects: Organization-Level Removal (removes user from all projects):- Go to Organization → Settings → Team
- Find the user in the Members tab
- Click the delete icon
- Confirm removal
- Go to Project → Settings → Team
- Change the user’s project role to “No Project Role”
- User loses access to this project but keeps access to other projects
Best Practices
Principle of Least Privilege
Grant the minimum permissions needed for each team member to do their job: Bad Practice:- Making everyone Organization Admin “just to be safe”
- Giving Project Owner to anyone who asks for access
- Using broad permissions when narrow ones would work
- Start with Organization Member for all users
- Grant project-specific roles based on actual responsibilities
- Use custom roles for specialized needs
- Regularly audit and reduce excessive permissions
Separate Development and Production Access
Use different permission levels across environments: Development/Staging Projects:- Grant Project Admin to developers and testers
- Allow experimentation and testing
- Enable full access to logs and debugging tools
- Limit to Project Member for most team members
- Reserve Project Owner for senior engineers
- Require change approval workflows
- Separate deployment permissions from development access
Use Custom Roles for Contractors
Create specialized roles for external consultants and temporary team members:Audit Roles Regularly
Review team access quarterly:1
Export Member List
Document all team members and their current roles
2
Verify Continued Need
Check if each person still needs their current access level
3
Remove Departed Users
Delete accounts for people who left the organization
4
Update Changed Responsibilities
Adjust roles for people whose job duties changed
Document Role Assignments
Create internal documentation explaining:- Which role to assign for each job function
- Approval process for role changes
- Who can grant Organization Owner or Admin
- Custom role purposes and use cases
Plan for Role Escalation
Establish clear processes for temporary privilege escalation: Emergency Access:- Who can grant temporary elevated permissions
- Maximum duration for elevated access
- Requirement to document reason
- Automatic or manual downgrade after incident
- Request process for temporary Project Owner access
- Change window documentation
- Post-maintenance role reset
Monitor Permission Changes
Track who modifies roles and access:- Review audit logs for role assignments
- Set up alerts for organization role changes
- Monitor bulk permission grants
- Investigate unexpected access pattern changes
botBrains maintains audit logs of all permission changes, including who made the change, when, and what was modified. Use these logs for compliance reporting and security investigations.
Common Scenarios
Scenario: Onboarding a Support Team Member
Goal: Give a new support agent access to view conversations and update knowledge Solution:- Assign Organization Member role
- Assign Project Member role in relevant support projects
- Team member can:
- View and label conversations
- Create and update knowledge snippets
- View analytics
- Team member cannot:
- Modify deployments
- Delete knowledge sources
- Access other projects
- Manage team members
Scenario: External Consultant Review
Goal: Allow a consultant to review AI performance without data export capabilities Solution:- Create custom “Consultant” role with permissions:
- conversation:read
- metric:read
- topic:read
- guidance:read
- knowledge:read
- Assign Organization Member (no org-level access)
- Assign Consultant role to specific projects
- Consultant can review but not export or modify
Scenario: Multi-Brand Organization
Goal: Separate teams manage different bran AI agents Solution:- Create separate projects for each brand
- Assign Organization Member to all team members
- Grant Project Owner to brand-specific team leads
- Grant Project Member to team members working on that brand
- Executives get Project Viewer across all brands for oversight
Scenario: Reducing Access for Departing Employee
Goal: Limit access during notice period Solution:- Immediately change organization role to Organization Member
- Downgrade all project roles to Project Viewer
- Remove API key access
- Monitor audit logs for unusual activity
- Delete account on final day
Scenario: Temporary Access for Testing
Goal: Give QA team elevated permissions during testing phase Solution:- Create separate testing project (clone of production)
- Grant Project Admin in testing project
- Keep Project Viewer in production project
- After testing, delete testing project or revoke access
Troubleshooting
”I changed the role but the user still has access”
Cause: User has broader organization role that grants the permissions Solution: Check both organization and project roles. Demote organization role to Organization Member to enable true project-level control.”User can’t see the project they were invited to”
Possible Causes:- Invitation not yet accepted - check Invitations tab
- Assigned “No Project Role” - assign appropriate project role
- User signed in with different email - check email match
- Browser cache - try incognito mode or clear cache
”Custom role is missing required permissions”
Cause: Permission dependencies not understood Solution: Review permission categories above. Some actions require multiple permissions (e.g., updating deployments requires both deployment:read and deployment:update).”Can’t remove team member”
Cause: Only Organization Admins can remove members Solution: Ask an Organization Owner or Admin to remove the user, or change your own organization role if appropriate.”Permission changes aren’t taking effect”
Solution:- Verify role change was saved (check Members table)
- Ask user to sign out and sign back in
- Check browser console for errors
- Verify organization role isn’t overriding project restrictions
Security Considerations
Protect Organization Owner Access
The Organization Owner role has complete control:- Limit to 1-2 trusted individuals
- Use strong passwords and 2FA
- Never share credentials
- Rotate access if someone leaves
- Monitor audit logs for owner actions
Secure API Keys by Role
API keys inherit permissions from the role of the user who created them:- Restrict project_apikey:write to trusted roles
- Rotate keys regularly
- Revoke keys when team members leave
- Use separate keys for different environments
- Never commit keys to version control
Review Access After Security Incidents
If you suspect unauthorized access:- Change Organization Owner password immediately
- Review audit logs for unusual activity
- Revoke all API keys and generate new ones
- Review all user roles and remove unnecessary access
- Enable 2FA for all organization members
- Consider rotating sensitive data
Compliance and Data Protection
Meet regulatory requirements with proper role configuration: GDPR Compliance:- Restrict full_export:read to authorized personnel
- Use Project Viewer for data minimization
- Audit who accesses customer conversations
- Implement role-based data retention policies
- Document role assignment procedures
- Maintain audit trail of permission changes
- Review access quarterly
- Implement separation of duties with custom roles
Next Steps
Now that you understand roles and permissions, explore related security features:- API Keys - Generate and manage programmatic access
- Triggers - Automate actions based on events
- Team Management - Invite and organize team members
- Organization Settings - Configure organization-level policies