Skip to main content
Organization Settings provide centralized control over your botBrains account, including team management, billing, subscription plans, and organization-level security policies. These settings apply across all projects and determine how your entire team collaborates on AI customer service.

​
Why Organization Settings Matter

Organization settings enable you to:
  • Control costs - Monitor usage, manage subscriptions, and track billing across all projects
  • Secure your account - Define roles, manage permissions, and control who can access what
  • Scale your team - Invite members, assign organization-level access, and manage collaboration
  • Maintain consistency - Set default configurations that apply to new projects
  • Track accountability - Monitor usage patterns and identify which projects consume resources
Organization vs Project Settings: Organization settings affect your entire account and all projects. For project-specific configurations like AI behavior, knowledge sources, or deployment channels, use Project Settings.

​
Organization Overview

​
What’s Included

Your organization encompasses:
  • All projects - Ever AI agent, deployment, and configuration
  • Team members - Users who can create, manage, or view projects
  • Billing account - Subscription plans, usage tracking, and payment information
  • Shared resources - User pools that can span multiple projects
  • Organization roles - Permissions that grant access across all projects

​
Single Organization Model

Each botBrains account has exactly one organization. All your projects, team members, and billing roll up to this organization level. This centralized model simplifies administration and provides a single source of truth for your account.

​
Accessing Organization Settings

To access Organization Settings:
  1. Click your organization name in the top-left corner of the sidebar
  2. Select Settings from the organization menu
  3. You’ll see the Organization Settings overview page with sections for Team, Billing, and Organization management
You need organization-level admin permissions to access most organization settings. If you don’t see the Settings option, contact your organization admin to request access.

​
Team Management

Team management controls who can access your organization and what they can do within it. This is where you invite colleagues, assign organization-wide roles, and manage member access.

​
Organization Roles vs Project Roles

botBrains uses a two-tier permission system: Organization Roles apply to all projects:
  • Organization Owner - Full control over organization, billing, and all projects
  • Organization Admin - Can manage all projects and team members, but cannot modify billing
  • Organization Member - No automatic project access; must be granted project-specific roles
Project Roles apply to individual projects:
  • Project roles provide granular control over what team members can do within specific projects
  • Team members can have different roles in different projects
  • Organization Owners and Admins automatically have access to all projects

​
Why Use Organization Member Role

Assign most team members the Organization Member role to enable granular access control:
  • Least privilege - Members start with zero access and only get what they need
  • Project isolation - Team members only see projects relevant to their work
  • Easier auditing - Clear visibility into who has access to what
  • Reduced risk - Limit exposure if a team member account is compromised
Organization Admin Override: Even if you demote a team member’s project role to restrict access, they’ll retain full access if they have Organization Admin or Owner roles. Always check both organization and project roles when managing permissions.

​
Inviting Team Members

To invite someone to your organization:
  1. Navigate to Settings > Team
  2. Click Invite user in the top-right
  3. Enter their email address
  4. Select an Organization Role (Owner, Admin, or Member)
  5. Optionally assign Project Roles for specific projects
  6. Click Send Invitation
The invited user receives an email with a link to join your organization. Once they accept, they’ll have access according to the roles you assigned.

​
Managing Invitations

View and manage pending invitations on the Invitations tab:
  • Pending invitations - See who you’ve invited but hasn’t joined yet
  • Resend - Send invitation email again if it wasn’t received
  • Revoke - Cancel an invitation before it’s accepted
  • Expiration - Invitations expire after 7 days and must be resent

​
Managing Team Members

On the Members tab, you can:
  • View all members - See everyone with access to your organization
  • Change organization roles - Promote or demote members between Owner, Admin, and Member
  • View project roles - See what project-level permissions each member has
  • Remove members - Revoke access for team members who no longer need it
Removing a team member from the organization immediately revokes their access to all projects, deployments, and data. Make sure you’ve transferred ownership of any critical work before removing someone.

​
Role Inheritance

Understanding how roles interact is critical for security: Highest role wins: If a team member has both an organization role and project role, they get the union of all permissions. Example scenarios: 
Scenario 1: Restricted Access
- Organization Role: Member (no automatic access)
- Project Role: Viewer (read-only for Project A)
→ Result: Can only view Project A, no other access

Scenario 2: Admin Override
- Organization Role: Admin (access to everything)
- Project Role: Viewer (attempted restriction for Project A)
→ Result: Full admin access to Project A and all other projects
Best practice: Use Organization Member for most team members, then assign specific project roles as needed. Reserve Organization Admin and Owner for true administrators.

​
Billing and Usage

Billing management gives you visibility into costs, usage patterns, and subscription details across all your projects.

​
Usage Monitoring

Track resource consumption and predict costs on the Usage page: Current billing cycle metrics:
  • Current bill - Actual charges month-to-date based on usage
  • Projected bill - Estimated total cost if usage continues at current rate
  • Projected pay-as-you-go - Additional charges if you exceed plan limits
Line item tracking:
  • Generated messages - AI responses sent to users across all projects
  • Projects - Number of active projects in your organization
  • Usage vs capacity - Visual progress bars showing consumption against plan limits
  • Overage warnings - Alerts when you’re approaching or exceeding plan limits
Check the Usage page regularly to avoid surprise bills. If you’re consistently exceeding plan limits, consider upgrading your subscription rather than paying higher pay-as-you-go rates.

​
Understanding Usage Calculations

Current cost calculation: 
Current Cost = (Base subscription rate) + (Overage usage × Pay-as-you-go rate)
Projected cost calculation: 
Projected Cost = (Usage to date ÷ Days elapsed) × Days in month
Projections assume your usage rate stays constant through the end of the billing period. Actual costs may vary based on your usage patterns.

​
Usage History

View historical usage data to identify trends and plan capacity:
  • Past billing periods - See usage and costs for previous months
  • Trend analysis - Identify seasonal patterns or growth trends
  • Project breakdowns - Understand which projects consume the most resources
  • Export data - Download usage reports for accounting or analysis

​
Subscription Management

Manage your plan and billing details on the Subscription page: Subscription details:
  • Plan status - Active, trial, cancelled, or expired
  • Start date - When your current subscription began
  • Next renewal - When you’ll be billed next
  • Contract period - Length of your commitment (monthly, annual, etc.)
  • Trial end - If applicable, when trial period expires
Line items:
  • Committed capacity - What’s included in your base subscription
  • Rate structure - Per-unit pricing for base capacity and overages
  • Volume allowances - How many messages or projects are included
  • Pay-as-you-go rates - Pricing for usage beyond plan limits

​
Managing Your Subscription

Common subscription management tasks: Upgrading your plan:
  1. Navigate to Settings > Billing > Subscription
  2. Review current plan and usage patterns
  3. Contact sales or support to discuss plan options
  4. Changes typically take effect at next billing cycle
Viewing billing history:
  1. Navigate to Settings > Billing > Usage
  2. Scroll to Usage History section
  3. Review past billing periods and charges
  4. Export data if needed for accounting
Updating payment methods:
  • Payment method management is handled through the billing portal
  • Access via Subscription page or billing emails
  • Changes apply immediately for future charges
Trial periods: If you’re on a trial, charges begin automatically when the trial expires. Make sure to review pricing and usage before your trial ends to avoid unexpected bills.

​
Pay-as-You-Go vs Committed Capacity

Understanding the pricing model helps you optimize costs: Committed capacity (base plan):
  • Fixed monthly fee for predictable costs
  • Lower per-unit rates than pay-as-you-go
  • Includes allowance for messages and projects
  • Best for steady, predictable usage
Pay-as-you-go (overage):
  • Higher per-unit rates for usage beyond plan
  • No upfront commitment, scales automatically
  • Charges appear on next invoice
  • Best for occasional spikes or unpredictable usage
Cost optimization strategies:
  1. Right-size your plan - If you consistently exceed capacity, upgrade to avoid higher overage rates
  2. Monitor early in cycle - Check usage in the first week to project month-end costs
  3. Set internal alerts - Assign someone to review usage weekly and take action before overages occur
  4. Consolidate projects - Consider if multiple projects can be merged to reduce per-project fees
  5. Review inactive deployments - Pause or delete deployments that aren’t actively serving customers

​
Organization Profile Management

Organization profile settings control your organization’s identity and core configuration.
Feature availability: Organization profile editing is currently available to internal users and select customers. If you need to change your organization name or delete your organization, contact support.

​
Organization Name

Your organization name appears throughout the platform:
  • Organization selector in sidebar
  • Team invitation emails
  • Billing statements
  • API authentication contexts
A clear organization name helps team members understand which account they’re working in, especially if they belong to multiple organizations.

​
Deleting Your Organization

Deleting an organization is permanent and cannot be undone. When you delete your organization:
  • All projects are deleted - Including deployments, knowledge bases, and configurations
  • All data is removed - Conversations, analytics, and training data are permanently deleted
  • Team access is revoked - All team members lose access immediately
  • Billing stops - Subscription is cancelled and no further charges occur
Before deleting: Export any data you need to retain, notify your team, and ensure no active deployments are serving customers. Deletion is immediate and irreversible.

​
Security Best Practices

Follow these practices to keep your organization secure:

​
Role Management

Principle of least privilege:
  • Default new team members to Organization Member role
  • Grant Organization Admin only to those who truly need it
  • Regularly audit who has admin access
  • Remove access promptly when team members leave
Project-level granularity:
  • Use project roles to restrict access to specific projects
  • Don’t rely on Organization Admin for day-to-day work
  • Create custom project roles for specific workflows
  • Review project access quarterly

​
Access Monitoring

Regular audits:
  • Monthly review of organization members and their roles
  • Quarterly check of project-level permissions
  • Annual comprehensive security review
  • Document who approved each access grant
Offboarding checklist:
  1. Remove from organization (revokes all access)
  2. Verify removal completed successfully
  3. Document access revocation date
  4. Transfer ownership of any custom roles or configurations

​
API Key Security

While API keys are project-specific, organization admins can access all project API keys:
  • Rotate keys regularly - Especially after team member departures
  • Limit distribution - Only share keys with systems/people that need them
  • Monitor usage - Review API logs for suspicious activity
  • Use key scoping - Create project-specific keys rather than reusing across projects
Learn more in API Keys.

​
Troubleshooting

​
Common Issues

“I can’t access organization settings”
  • You need Organization Owner or Admin role
  • Check your role on the Members tab (ask an admin to check for you)
  • If you should have access, ask an owner to promote your role
“Team member can’t see a project after invitation”
  • Verify they accepted the invitation (check Invitations tab)
  • Confirm they were assigned a project role, not just organization role
  • Organization Member role doesn’t grant automatic project access
  • Have an admin assign them a role in the specific project
“Usage numbers don’t match expectations”
  • Usage updates with a short delay (typically 5-15 minutes)
  • Check Usage History to verify which projects are consuming resources
  • Ensure you’re looking at the correct billing period
  • Message counts include both user and AI messages
“Can’t remove a team member”
  • Only Organization Admins and Owners can remove members
  • You cannot remove the last owner (promote someone else first)
  • Some organizations require multiple owners for safety
“Projected bill seems too high”
  • Projections extrapolate current usage rate through month-end
  • Usage often front-loads (testing, training) then stabilizes
  • Review Usage page line items to identify high-consumption projects
  • Consider upgrading plan if you’re consistently exceeding capacity

​
Getting Help

If you encounter issues with organization settings:
  1. Check permissions - Verify you have the correct organization role
  2. Review documentation - Consult related guides like Team Management and Billing
  3. Contact support - Reach out via the platform or email support@botbrains.io
  4. Request access - If you need capabilities beyond your current role, ask your organization owner
Explore related topics to make the most of your organization:

Team Management

Invite members, assign roles, and manage collaboration across projects

Roles and Permissions

Understand permission levels and create custom roles for specific workflows

Billing

Deep dive into pricing plans, usage tracking, and cost optimization

Project Settings

Configure project-specific settings like language, timezone, and support email

API Keys

Generate and manage API keys for programmatic access to your projects

​
Next Steps

Now that you understand organization settings:
  1. Audit your team - Review current members and ensure roles align with responsibilities
  2. Monitor usage - Set a reminder to check usage weekly during your first month
  3. Right-size your plan - After a full billing cycle, evaluate if your plan matches your usage
  4. Document your structure - Create an internal guide explaining your organization’s role hierarchy
  5. Plan for growth - Consider how you’ll organize projects and teams as you scale