Organization Management Guide 🟡 BETA

This guide covers how to manage organizations in General Bots, including creating organizations, managing members, configuring settings, and switching between organizations.

Overview

Organizations are the top-level tenant in General Bots, providing:

• Complete Data Isolation: Each organization has separate bots, knowledge bases, and data
• Independent Billing: Separate subscriptions and quotas per organization
• Member Management: Users can belong to multiple organizations
• Custom Settings: Branding, security policies, and preferences per organization

Creating an Organization

Via UI

1. Click your profile avatar in the top-right corner
2. Click Create Organization
3. Fill in the organization details:
   • Name: Display name for the organization
   • Slug: URL-friendly identifier (auto-generated from name)
   • Description: Optional description
4. Click Create

Via API

POST /api/organizations
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Acme Corporation",
  "description": "Main organization for Acme Corp"
}

Response:

{
  "organization": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Acme Corporation",
    "slug": "acme-corporation",
    "description": "Main organization for Acme Corp",
    "plan_id": "free",
    "owner_id": "user-uuid",
    "created_at": "2025-01-21T10:00:00Z"
  },
  "roles": [...],
  "groups": [...],
  "owner_member": {...},
  "owner_role": {...}
}

When you create an organization, you automatically become the owner with full permissions.

Organization Structure

Each organization includes:

Organization
├── Settings
│   ├── General (name, logo, website)
│   ├── Security (2FA, SSO, IP whitelist)
│   ├── Branding (colors, custom CSS)
│   └── Billing (plan, quotas)
├── Members
│   ├── Users
│   ├── Roles
│   └── Groups
├── Bots
│   └── [bot configurations]
├── Apps
│   ├── Forms
│   ├── Sites
│   └── Projects
└── Knowledge Bases
    └── [.gbkb packages]

Managing Members

Inviting Members

1. Navigate to Settings → Members
2. Click Invite Member
3. Enter email address and select role
4. Click Send Invitation

POST /api/organizations/{org_id}/invitations
Authorization: Bearer <token>
Content-Type: application/json

{
  "email": "newuser@company.com",
  "role": "member"
}

Member Roles

When inviting members, assign an appropriate role:

Accepting Invitations

Invited users receive an email with a link to accept the invitation:

1. Click the invitation link
2. Sign in or create an account
3. Review organization details
4. Click Accept Invitation

Removing Members

1. Navigate to Settings → Members
2. Find the member in the list
3. Click the menu icon (⋮)
4. Select Remove from Organization

DELETE /api/organizations/{org_id}/members/{user_id}
Authorization: Bearer <token>

Organization Settings

General Settings

Security Settings

Custom Branding

Configuration Example

settings:
  allow_public_bots: false
  require_2fa: true
  allowed_email_domains:
    - company.com
    - subsidiary.com
  default_user_role: member
  max_members: 100
  sso_enabled: true
  sso_provider: okta
  audit_log_retention_days: 365
  ip_whitelist:
    - 10.0.0.0/8
    - 192.168.1.0/24
  custom_branding:
    primary_color: "#0066cc"
    secondary_color: "#004499"
    logo_url: "https://cdn.company.com/logo.svg"

Switching Organizations

Users who belong to multiple organizations can switch between them.

Via UI

1. Click your profile avatar or the organization name
2. A dropdown shows all your organizations
3. Click the organization to switch to

Via API

POST /api/user/switch-organization
Authorization: Bearer <token>
Content-Type: application/json

{
  "org_id": "target-organization-uuid"
}

The response includes a new session token scoped to the selected organization.

Organization Switcher Component

The organization switcher displays:

• Current organization name and logo
• User’s role in current organization
• List of other organizations
• Quick actions (create new, manage current)

<div class="org-selector">
  <div class="selected-org">
    <div class="org-avatar">AC</div>
    <div class="org-info">
      <span class="org-name">Acme Corporation</span>
      <span class="org-role">Admin</span>
    </div>
  </div>
  <div class="org-dropdown">
    <div class="org-dropdown-item">
      <div class="org-avatar">XY</div>
      <span>XYZ Partners</span>
    </div>
    <div class="org-dropdown-actions">
      <button>+ Create Organization</button>
    </div>
  </div>
</div>

Quotas and Limits

Each organization has quotas based on their plan:

Checking Usage

GET /api/organizations/{org_id}/usage
Authorization: Bearer <token>

Response:

{
  "organization_id": "org-uuid",
  "period": "2025-01",
  "quotas": {
    "members": { "used": 12, "limit": 50, "percent": 24 },
    "storage_mb": { "used": 5120, "limit": 51200, "percent": 10 },
    "api_calls": { "used": 45000, "limit": 500000, "percent": 9 },
    "messages": { "used": 8500, "limit": 100000, "percent": 8.5 }
  }
}

Deleting an Organization

Only the organization owner can delete an organization.

1. Navigate to Settings → General
2. Scroll to Danger Zone
3. Click Delete Organization
4. Type the organization name to confirm
5. Click Delete Permanently

DELETE /api/organizations/{org_id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "confirmation": "organization-name"
}

Deletion is permanent and removes:

• All organization data
• All bots and configurations
• All knowledge bases
• All apps (Forms, Sites, Projects)
• All member associations
• All billing data

Multi-Organization Patterns

Separate Environments

Use organizations for dev/staging/production:

Acme Corp - Development
Acme Corp - Staging
Acme Corp - Production

Department Isolation

Separate organizations per department:

Acme Corp - Sales
Acme Corp - Support
Acme Corp - Engineering

Client Projects

Agencies can create organizations per client:

Client A - Project X
Client B - Project Y
Internal - Agency Tools

API Reference

List User’s Organizations

GET /api/user/organizations
Authorization: Bearer <token>

Get Organization Details

GET /api/organizations/{org_id}
Authorization: Bearer <token>

Update Organization

PATCH /api/organizations/{org_id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "New Name",
  "description": "Updated description"
}

List Organization Members

GET /api/organizations/{org_id}/members
Authorization: Bearer <token>

Update Organization Settings

PUT /api/organizations/{org_id}/settings
Authorization: Bearer <token>
Content-Type: application/json

{
  "require_2fa": true,
  "allowed_email_domains": ["company.com"]
}

Best Practices

1. Clear Naming Conventions

Use consistent naming for multiple organizations:

[Company] - [Environment/Purpose]
Acme Corp - Production
Acme Corp - Development

2. Appropriate Role Assignment

Don’t over-assign admin roles:

• One or two owners maximum
• Admins for department heads
• Managers for team leads
• Members for everyone else

3. Regular Member Audits

Review members quarterly:

• Remove departed employees
• Adjust roles as responsibilities change
• Check for inactive accounts

4. Security Configuration

For enterprise organizations:

• Enable 2FA requirement
• Configure SSO if available
• Set IP whitelist for office networks
• Increase audit log retention

5. Quota Monitoring

Set up alerts for quota usage:

• 80% warning for planning
• 90% critical for immediate action
• Monitor trends over time

Related Topics

• RBAC Configuration
• Subscription & Billing
• Security Matrix
• SOC 2 Compliance