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

# Multi-Organization Setup Guide

> Manage multiple organizations, switch contexts, and organize your workspaces

## What You'll Learn

This guide covers managing multiple organizations in Junis:

* **Why Multiple Organizations**: Use cases and benefits
* **Creating Additional Organizations**: Step-by-step setup
* **Organization Switching**: Seamless context switching
* **Cross-Organization Features**: What's shared and what's isolated
* **Common Scenarios**: Agency, enterprise, dev/prod separation
* **Best Practices**: Naming, structure, and organization strategies

<Info>
  **Who This Is For**: Users who need to manage multiple projects, clients, or environments within Junis.
</Info>

***

## Why Multiple Organizations?

### Common Use Cases

<CardGroup cols={2}>
  <Card title="Agency/Consultancy" icon="briefcase">
    **Scenario**: Manage separate workspaces for each client

    **Benefits**:

    * Complete data isolation per client
    * Separate billing and feature limits
    * Client-specific branding and settings
    * Easy client handoff (transfer ownership)

    **Example**:

    * `acme-corp` (client A)
    * `globex-industries` (client B)
    * `initech-consulting` (your internal workspace)
  </Card>

  <Card title="Enterprise Departments" icon="building">
    **Scenario**: Separate organizations for different departments

    **Benefits**:

    * Department-level autonomy
    * Isolated agent configurations
    * Department-specific analytics
    * Compliance and governance per department

    **Example**:

    * `acme-marketing`
    * `acme-sales`
    * `acme-engineering`
    * `acme-data-science`
  </Card>

  <Card title="Dev/Staging/Production" icon="flask">
    **Scenario**: Separate environments for development lifecycle

    **Benefits**:

    * Test changes safely in dev
    * Isolated data per environment
    * Different feature flags per environment
    * Production safety

    **Example**:

    * `mycompany-dev`
    * `mycompany-staging`
    * `mycompany-production`
  </Card>

  <Card title="Personal + Professional" icon="user-tie">
    **Scenario**: Separate personal projects from work

    **Benefits**:

    * Work-life separation
    * Different billing accounts
    * Personal experimentation space
    * Professional client work

    **Example**:

    * `john-doe-personal`
    * `john-doe-freelance`
    * `acme-corp` (employer)
  </Card>
</CardGroup>

### Single vs Multiple Organizations

| Aspect              | Single Organization           | Multiple Organizations               |
| ------------------- | ----------------------------- | ------------------------------------ |
| **Data Isolation**  | All data in one workspace     | Complete isolation per organization  |
| **Billing**         | One bill for everything       | Separate billing per organization    |
| **Team Management** | One team roster               | Separate teams per organization      |
| **Agent Sharing**   | Agents shared across projects | Agents isolated per organization     |
| **Use Case**        | Small teams, single project   | Agencies, enterprises, multi-project |

<Check>
  **When to Use Multiple Organizations**:

  * Managing multiple clients
  * Separating dev/staging/prod environments
  * Different departments with separate budgets
  * Projects with different compliance requirements
  * Testing new features in isolation
</Check>

<Warning>
  **When NOT to Use Multiple Organizations**:

  * Single project with multiple sub-projects (use agent tagging instead)
  * Small team working on one product
  * Just to separate different agent types (use agent naming/folders instead)
</Warning>

***

## Creating Additional Organizations

### Prerequisites

<Check>
  * Existing Junis account (verified email)
  * At least one organization already created (from onboarding)
  * Organization approval pending or approved
</Check>

### Step-by-Step Creation

<Steps>
  <Step title="Access Organization Switcher">
    Click the **organization name** in the top-left corner of the dashboard.

    Or navigate to **Settings > Organizations** in the sidebar.
  </Step>

  <Step title="Click 'Create New Organization'">
    In the organization switcher dropdown, click **"+ Create New Organization"** at the bottom.
  </Step>

  <Step title="Fill in Organization Details">
    **Required Fields**:

    * **Organization Name**: Display name (e.g., "Acme Corp - Marketing")
    * **Slug**: URL-friendly identifier (e.g., "acme-marketing")
      * Auto-generated from name
      * Can be customized
      * Must be unique across all Junis organizations

    **Optional Fields**:

    * **Description**: Organization purpose or description
    * **Logo**: Upload organization logo (PNG, JPG, max 2MB)
    * **Welcome Suggestions**: Custom chat suggestions for this organization
  </Step>

  <Step title="Configure Initial Settings">
    **Organization Type**: (Auto-selected: STANDARD)

    **Initial Features**:

    * Max Agents: 10 (default, can be increased)
    * Max Members: 50 (default)
    * Max Sessions/Day: 1,000 (default)
    * RAG Enabled: Yes (default)

    <Info>
      Feature limits can be adjusted later by administrators.
    </Info>
  </Step>

  <Step title="Submit for Approval">
    Click **"Create Organization"**.

    **What Happens Next**:

    1. Organization created with `PENDING` status
    2. You become the OWNER automatically
    3. Default orchestrator agent created (`orchestrator-{slug}`)
    4. Approval notification sent to Junis administrators

    **Approval Timeline**: 1-2 business days
  </Step>

  <Step title="Wait for Approval">
    **While PENDING**:

    * Organization appears in your organization list
    * Yellow "Pending Approval" badge displayed
    * You can view organization settings but cannot use agents

    **After APPROVAL**:

    * Status changes to `ACTIVE`
    * Green "Active" badge displayed
    * All features unlocked
    * You can invite team members and create agents
  </Step>
</Steps>

### Organization Creation via API

**Endpoint**: `POST /api/organizations`

**Request Body**:

```json theme={null}
{
  "name": "Acme Corp - Marketing",
  "slug": "acme-marketing",
  "description": "Marketing department workspace",
  "logo_url": "https://example.com/logo.png",
  "welcome_suggestions": [
    "Analyze this campaign performance",
    "Generate social media content ideas",
    "Create a content calendar"
  ]
}
```

**Response**:

```json theme={null}
{
  "id": "org-uuid-1234",
  "name": "Acme Corp - Marketing",
  "slug": "acme-marketing",
  "status": "PENDING",
  "org_type": "STANDARD",
  "created_at": "2026-01-01T10:00:00Z",
  "created_by": "user-uuid-5678",
  "features": {
    "max_agents": 10,
    "max_members": 50,
    "max_sessions_per_day": 1000,
    "rag_enabled": true
  }
}
```

***

## Switching Between Organizations

### Using the Organization Switcher

<Tabs>
  <Tab title="Desktop/Web">
    **Location**: Top-left corner of the dashboard (next to Junis logo)

    **Steps**:

    1. Click the **current organization name** (e.g., "Acme Marketing")
    2. Dropdown shows all your organizations
    3. Click the organization you want to switch to
    4. Page reloads with new organization context

    **Keyboard Shortcut**: `Cmd+K` (Mac) / `Ctrl+K` (Windows) → Type organization name → Enter
  </Tab>

  <Tab title="Mobile/Tablet">
    **Location**: Hamburger menu (☰) → "Switch Organization"

    **Steps**:

    1. Tap the **hamburger menu** (☰) in the top-left
    2. Tap **"Switch Organization"**
    3. Select organization from list
    4. App reloads with new context
  </Tab>

  <Tab title="API">
    **Endpoint**: `POST /api/organizations/{organization_id}/switch`

    **Request**:

    ```bash theme={null}
    curl -X POST https://api.junis.ai/api/organizations/org-uuid-1234/switch \
      -H "Authorization: Bearer YOUR_TOKEN"
    ```

    **Response**:

    ```json theme={null}
    {
      "message": "Switched to organization: Acme Marketing",
      "organization_id": "org-uuid-1234",
      "organization_name": "Acme Marketing",
      "new_token": "eyJhbGciOi..."  // New JWT with org_id
    }
    ```

    **Important**: Store the new token! It includes the organization context.
  </Tab>
</Tabs>

### What Changes When You Switch

<Tabs>
  <Tab title="UI Changes">
    **Visible Changes**:

    * Organization name in header updates
    * Logo changes (if custom logo set)
    * Welcome suggestions update
    * Sidebar navigation shows organization-specific items

    **Dashboard**:

    * Agents list filtered to current organization
    * Sessions filtered to current organization
    * Analytics show current organization data only
    * Team members list shows current organization roster
  </Tab>

  <Tab title="API Context">
    **JWT Token Updated**:

    ```json theme={null}
    {
      "user_id": "user-uuid-5678",
      "organization_id": "org-uuid-1234",  // ← Updated
      "role": "OWNER",
      "permissions": { /* org-specific permissions */ },
      "exp": 1767261600
    }
    ```

    **All API Requests**:

    * Automatically scoped to current organization
    * Cannot access other organization's data
    * WebSocket connections tied to organization
  </Tab>

  <Tab title="Data Isolation">
    **What You See**:

    * Only agents from current organization
    * Only sessions from current organization
    * Only team members from current organization
    * Only RAG Datastores from current organization

    **What You DON'T See**:

    * Other organizations' agents (even if you're a member)
    * Other organizations' sessions
    * Other organizations' data
  </Tab>
</Tabs>

### Organization Context Persistence

<Info>
  **Session Persistence**: Your last selected organization is remembered across browser sessions.
</Info>

**How It Works**:

1. Organization choice stored in JWT token
2. JWT token saved in browser localStorage
3. On next visit, last organization is auto-selected
4. You can switch anytime using the organization switcher

***

## Managing Multiple Organizations

### Organization List View

**Location**: Click organization name → "Manage Organizations"

**What You See**:

<Tabs>
  <Tab title="Your Organizations">
    **List of Organizations You Own or Are a Member Of**:

    | Organization        | Status       | Role   | Members | Agents | Last Active |
    | ------------------- | ------------ | ------ | ------- | ------ | ----------- |
    | Acme Marketing      | 🟢 Active    | OWNER  | 12      | 25     | 2 hours ago |
    | Acme Sales          | 🟢 Active    | ADMIN  | 8       | 15     | 1 day ago   |
    | Personal Workspace  | 🟡 Pending   | OWNER  | 1       | 3      | 5 days ago  |
    | ClientCo Consulting | 🔴 Suspended | MEMBER | 5       | 10     | 3 weeks ago |

    **Actions**:

    * 🔄 **Switch**: Switch to this organization
    * ⚙️ **Settings**: Edit organization settings (OWNER/ADMIN only)
    * 👥 **Members**: View/manage team members
    * 🚪 **Leave**: Leave organization (if not last OWNER)
  </Tab>

  <Tab title="Pending Invitations">
    **Organizations You're Invited To But Haven't Joined**:

    | Organization        | Invited By                                        | Role   | Invited Date | Actions              |
    | ------------------- | ------------------------------------------------- | ------ | ------------ | -------------------- |
    | NewClient Workspace | [alice@newclient.com](mailto:alice@newclient.com) | MEMBER | Jan 1, 2026  | ✅ Accept / ❌ Decline |
    | Partner Agency      | [bob@partner.com](mailto:bob@partner.com)         | ADMIN  | Jan 1, 2026  | ✅ Accept / ❌ Decline |

    **Actions**:

    * ✅ **Accept**: Join organization with assigned role
    * ❌ **Decline**: Reject invitation permanently
    * ℹ️ **Details**: View organization details before accepting
  </Tab>

  <Tab title="Create New">
    **Create Additional Organization**:

    * Click **"+ Create New Organization"** button
    * Follow creation wizard
    * Submit for approval
    * New organization appears in your list with PENDING status
  </Tab>
</Tabs>

### Multi-Organization Dashboard

**Feature**: Unified view across all your organizations (coming soon)

**What It Will Show**:

* Total agents across all organizations
* Combined session count
* Activity timeline across organizations
* Quick organization switcher
* Notifications from all organizations

***

## Cross-Organization Features

### What's Shared Across Organizations

<CardGroup cols={2}>
  <Card title="User Account" icon="user">
    **Shared**:

    * User ID
    * Email address
    * Display name
    * Avatar
    * Password/authentication

    **Not Shared**:

    * Role (OWNER in org A ≠ OWNER in org B)
    * Permissions (org-specific)
  </Card>

  <Card title="Global Platform Access" icon="globe">
    **Shared**:

    * Platform features (MCP, RAG, Payment)
    * Global LLM models
    * Junis platform updates
    * Documentation and support

    **Not Shared**:

    * Organization-specific feature limits
    * Organization-specific settings
  </Card>
</CardGroup>

### What's Isolated Per Organization

<Warning>
  **Complete Isolation**: The following are NEVER shared between organizations:
</Warning>

<Tabs>
  <Tab title="Data Isolation">
    **Completely Isolated**:

    * Agents (cannot see other org's agents)
    * Sessions (cannot access other org's conversations)
    * RAG Datastores (separate knowledge bases)
    * Agent Templates (organization-specific)
    * File Uploads (separate storage per org)
    * Usage Analytics (separate metrics)
  </Tab>

  <Tab title="Team Isolation">
    **Completely Isolated**:

    * Team members (separate rosters)
    * Roles and permissions (org-specific)
    * Invitations (cannot invite to other orgs)
    * Team settings (separate configurations)
  </Tab>

  <Tab title="Billing Isolation">
    **Completely Isolated** (when billing enabled):

    * Subscription plans (per organization)
    * Usage charges (per organization)
    * Payment methods (separate per org)
    * Invoices (org-specific)
    * Wallet addresses (for AP2/x402 revenue)
  </Tab>
</Tabs>

### Global Resources

**What Are Global Resources?**

Some platform features are shared across all organizations:

<CardGroup cols={2}>
  <Card title="LLM Models" icon="brain">
    **Shared Models**:

    * Anthropic Claude (all versions)
    * OpenAI GPT (all versions)
    * Google Gemini
    * DeepSeek, Qwen, etc.

    **How It Works**:

    * Models available to all organizations
    * Usage tracked per organization
    * API keys managed per organization
  </Card>

  <Card title="MCP Platforms" icon="plug">
    **Shared Platforms**:

    * GitHub, Firecrawl, 커스텀 MCP 등
    * Platform definitions shared
    * Credentials per-user or per-organization

    **How It Works**:

    * Platform capabilities available to all
    * Authentication per user or org
    * Usage isolated per organization
  </Card>

  <Card title="Tool Registry" icon="wrench">
    **Shared Tools**:

    * Brand search tools
    * Google search
    * File upload tools
    * Payment tools (AP2/x402)

    **How It Works**:

    * Tool definitions global
    * Tool usage tracked per organization
    * Tool results isolated per organization
  </Card>

  <Card title="Documentation" icon="book">
    **Shared Resources**:

    * Platform documentation
    * API reference
    * User guides
    * Support knowledge base

    **Always Available**:

    * Same docs for all users
    * Accessible from any organization
  </Card>
</CardGroup>

***

## Common Multi-Organization Scenarios

### Scenario 1: Agency Managing Multiple Clients

**Setup**:

```mermaid theme={null}
graph TB
    You[Your User Account] --> Org1[Agency Internal]
    You --> Org2[Client A]
    You --> Org3[Client B]
    You --> Org4[Client C]

    Org1 --> Team1[Your Team: 10 members]
    Org2 --> Team2[Client A: 3 members]
    Org3 --> Team3[Client B: 5 members]
    Org4 --> Team4[Client C: 2 members]
```

**Organization Structure**:

| Organization        | Role  | Members                  | Purpose                                  |
| ------------------- | ----- | ------------------------ | ---------------------------------------- |
| `myagency-internal` | OWNER | 10 (your team)           | Internal agency work, templates, testing |
| `clienta-workspace` | OWNER | 3 (you + 2 client staff) | Client A production agents               |
| `clientb-workspace` | OWNER | 5 (you + 4 client staff) | Client B production agents               |
| `clientc-workspace` | OWNER | 2 (you + 1 client staff) | Client C production agents               |

**Best Practices**:

* Use agency internal workspace for agent templates and testing
* Clone templates to client organizations
* Keep client data completely isolated
* Transfer ownership when client relationship ends
* Use consistent naming: `{clientname}-workspace`

### Scenario 2: Enterprise with Multiple Departments

**Setup**:

```mermaid theme={null}
graph TB
    Enterprise[Enterprise Corp] --> Marketing[Marketing Dept]
    Enterprise --> Sales[Sales Dept]
    Enterprise --> Eng[Engineering Dept]
    Enterprise --> Data[Data Science Dept]

    Marketing --> M1[Marketing Team: 20]
    Sales --> S1[Sales Team: 15]
    Eng --> E1[Engineering Team: 50]
    Data --> D1[Data Team: 10]
```

**Organization Structure**:

| Organization        | Role  | Members | Purpose                                 |
| ------------------- | ----- | ------- | --------------------------------------- |
| `acme-marketing`    | ADMIN | 20      | Marketing campaigns, content generation |
| `acme-sales`        | ADMIN | 15      | Sales automation, lead qualification    |
| `acme-engineering`  | ADMIN | 50      | Code generation, documentation          |
| `acme-data-science` | ADMIN | 10      | Data analysis, model training           |

**Benefits**:

* Department autonomy (each dept manages own agents)
* Separate billing (cost allocation per department)
* Compliance (different data policies per dept)
* Analytics (department-specific usage metrics)

**Coordination**:

* Platform admin has OWNER role in all departments
* Shared best practices document
* Cross-department agent templates (manual copy)
* Monthly usage review meetings

### Scenario 3: Dev/Staging/Production Environments

**Setup**:

```mermaid theme={null}
graph LR
    Dev[Development Org] --> Test1[Test Changes]
    Dev --> Exp[Experiment]

    Staging[Staging Org] --> UAT[User Testing]
    Staging --> QA[QA Validation]

    Prod[Production Org] --> Live[Live Agents]
    Prod --> Client[Client Use]

    Dev -.Clone agents.-> Staging
    Staging -.Promote.-> Prod
```

**Organization Structure**:

| Organization       | Role  | Members         | Purpose                               | Features                             |
| ------------------ | ----- | --------------- | ------------------------------------- | ------------------------------------ |
| `myapp-dev`        | OWNER | 5 (dev team)    | Development, testing, experimentation | All features enabled, relaxed limits |
| `myapp-staging`    | ADMIN | 3 (QA team)     | Pre-production testing, UAT           | Production-like limits               |
| `myapp-production` | OWNER | 2 (senior devs) | Live production environment           | Strict limits, monitoring            |

**Workflow**:

1. Develop new agents in `myapp-dev`
2. Test thoroughly in dev environment
3. Clone successful agents to `myapp-staging`
4. Perform UAT and QA validation
5. Manually recreate in `myapp-production` (safest)
6. Monitor production carefully

**Best Practices**:

* Never test in production
* Use different API keys per environment
* Separate RAG Datastores (dev uses test data)
* Different feature flags per environment
* Strict access control on production

### Scenario 4: Personal + Professional Workspaces

**Setup**:

```mermaid theme={null}
graph TB
    You[Your Account] --> Personal[Personal Workspace]
    You --> Freelance[Freelance Projects]
    You --> EmployerA[Employer A]
    You --> EmployerB[Employer B - Part Time]

    Personal --> P1[Side projects, learning]
    Freelance --> F1[Client work]
    EmployerA --> E1[Full-time job]
    EmployerB --> E2[Consulting work]
```

**Organization Structure**:

| Organization         | Role   | Billing              | Purpose                  |
| -------------------- | ------ | -------------------- | ------------------------ |
| `john-doe-personal`  | OWNER  | Personal credit card | Hobby projects, learning |
| `john-doe-freelance` | OWNER  | Business credit card | Client deliverables      |
| `acme-corp`          | MEMBER | Company billing      | Full-time job work       |
| `consulting-inc`     | ADMIN  | Client billing       | Part-time consulting     |

**Benefits**:

* Clear work-life separation
* Different billing accounts (personal vs business)
* Professional work stays with employer
* Freelance work is portable

**Best Practices**:

* Use work email for employer organizations
* Use personal email for personal workspace
* Never mix personal and professional data
* Archive freelance organizations after project ends

***

## Organization Naming Best Practices

### Naming Conventions

<Tabs>
  <Tab title="Agency/Consultancy">
    **Pattern**: `{agency-name}-{client-name}`

    **Examples**:

    * `innovate-agency-clienta`
    * `innovate-agency-clientb`
    * `innovate-agency-internal`

    **Benefits**:

    * Consistent naming across clients
    * Easy to identify your organizations
    * Alphabetical sorting keeps them grouped
  </Tab>

  <Tab title="Enterprise Departments">
    **Pattern**: `{company-name}-{department}`

    **Examples**:

    * `acme-corp-marketing`
    * `acme-corp-sales`
    * `acme-corp-engineering`
    * `acme-corp-data-science`

    **Benefits**:

    * Company prefix keeps all orgs together
    * Department name is clear
    * Easy to manage at scale
  </Tab>

  <Tab title="Environment Separation">
    **Pattern**: `{project-name}-{environment}`

    **Examples**:

    * `myapp-dev`
    * `myapp-staging`
    * `myapp-production`

    **Benefits**:

    * Clear environment identification
    * Prevents accidental production changes
    * Easy to switch between environments
  </Tab>

  <Tab title="Personal/Professional">
    **Pattern**: `{name}-{purpose}` or `{company-name}`

    **Examples**:

    * `john-doe-personal`
    * `john-doe-freelance`
    * `acme-corp` (employer)
    * `consulting-inc` (part-time)

    **Benefits**:

    * Clear ownership
    * Professional names for employer orgs
    * Personal identity for own workspaces
  </Tab>
</Tabs>

### Slug Best Practices

<Check>
  **✅ Good Slugs**:

  * `acme-corp-marketing` (clear, descriptive)
  * `clienta-workspace` (simple, purposeful)
  * `myapp-production` (environment clear)
  * `john-doe-personal` (ownership clear)
</Check>

<Warning>
  **❌ Bad Slugs**:

  * `org1`, `org2`, `org3` (meaningless)
  * `test`, `temp`, `sandbox` (too generic, conflicts likely)
  * `acme_corp` (use hyphens, not underscores)
  * `AcmeCorp` (lowercase only)
  * `my-super-long-organization-name-with-many-words` (too long)
</Warning>

***

## Billing and Features Across Organizations

### Per-Organization Billing (When Enabled)

<Info>
  **Current Status**: Junis is currently free during beta. Billing features will be enabled in future releases.
</Info>

**How It Will Work**:

| Feature            | Single Organization            | Multiple Organizations                 |
| ------------------ | ------------------------------ | -------------------------------------- |
| **Subscription**   | One subscription for all usage | Separate subscription per organization |
| **Billing**        | One invoice                    | Separate invoice per organization      |
| **Payment Method** | One credit card                | Different cards per organization       |
| **Usage Limits**   | Shared across all projects     | Isolated per organization              |
| **Overages**       | One overage charge             | Overage per organization               |

### Feature Limits Per Organization

Each organization has independent feature limits:

**Default Limits (STANDARD Organization)**:

```json theme={null}
{
  "max_agents": 10,              // Can create up to 10 agents
  "max_members": 50,             // Can invite up to 50 team members
  "max_sessions_per_day": 1000,  // 1,000 sessions per day
  "rag_enabled": true,           // RAG knowledge base enabled
  "payment_enabled": true,       // AP2/x402 payments enabled
  "mcp_platforms": true,         // MCP integrations enabled
  "scheduled_tasks": true        // Scheduled agent execution enabled
}
```

**Example: Multi-Organization Limits**:

| Organization        | Max Agents    | Max Members     | Max Sessions/Day       | RAG | MCP |
| ------------------- | ------------- | --------------- | ---------------------- | --- | --- |
| `myagency-internal` | 10            | 50              | 1,000                  | ✅   | ✅   |
| `clienta-workspace` | 10            | 50              | 1,000                  | ✅   | ✅   |
| `clientb-workspace` | 10            | 50              | 1,000                  | ✅   | ✅   |
| **Total**           | **30 agents** | **150 members** | **3,000 sessions/day** | -   | -   |

<Info>
  **Limits Add Up**: If you have 3 organizations, you get 3× the limits (10 agents × 3 = 30 total agents).
</Info>

***

## Troubleshooting Multi-Organization Issues

<AccordionGroup>
  <Accordion title="Cannot Find Organization in Switcher" icon="magnifying-glass">
    **Symptoms**: Organization doesn't appear in organization switcher dropdown

    **Possible Causes**:

    * Organization status is PENDING (not yet approved)
    * You were removed from the organization
    * Organization was deleted
    * Browser cache issue

    **Solutions**:

    1. Check organization status in **Settings > Organizations**
    2. Verify you're still a member (check email for removal notification)
    3. Clear browser cache and reload
    4. Try logging out and logging back in
    5. Contact organization OWNER to confirm membership
  </Accordion>

  <Accordion title="Switched Organization But See Wrong Data" icon="arrows-rotate">
    **Symptoms**: After switching, still see previous organization's agents/sessions

    **Possible Causes**:

    * Page didn't fully reload after switch
    * Browser cache showing stale data
    * API token not updated

    **Solutions**:

    1. Force refresh page: `Cmd+Shift+R` (Mac) / `Ctrl+Shift+R` (Windows)
    2. Clear browser cache
    3. Log out and log back in
    4. Check organization name in header (confirm switch succeeded)
    5. If using API, ensure you're using the new token from switch response
  </Accordion>

  <Accordion title="Cannot Create New Organization" icon="building-circle-xmark">
    **Symptoms**: "Create Organization" button disabled or shows error

    **Possible Causes**:

    * Email not verified
    * Organization limit reached (platform-level restriction)
    * Slug already taken
    * Invalid characters in organization name/slug

    **Solutions**:

    * Verify email if prompted
    * Try a different slug (must be globally unique)
    * Use only lowercase letters, numbers, and hyphens in slug
    * Contact support if you need more than 10 organizations
  </Accordion>

  <Accordion title="Lost Access to Organization" icon="lock">
    **Symptoms**: "Access Denied" or "Not Found" when trying to access organization

    **Possible Causes**:

    * You were removed from the organization
    * Organization was suspended or deleted
    * Your role was changed and you lost permissions
    * Organization is PENDING approval

    **Solutions**:

    * Check email for removal or role change notifications
    * Verify organization status in your organizations list
    * Contact organization OWNER or ADMIN
    * If organization is PENDING, wait for approval
  </Accordion>

  <Accordion title="Organization Stuck in PENDING" icon="clock">
    **Symptoms**: Organization created but status stays PENDING for > 2 business days

    **Possible Causes**:

    * Admin approval backlog
    * Organization name/purpose requires review
    * Missing required information

    **Solutions**:

    * Wait 1-2 business days after creation
    * Check email for approval requests or follow-up questions
    * Edit organization settings to provide more details
    * Contact Junis support at [contact@junis.ai](mailto:contact@junis.ai)
  </Accordion>

  <Accordion title="Cannot Transfer Organization Ownership" icon="user-crown">
    **Symptoms**: Trying to transfer OWNER role but operation fails

    **Current Status**: Organization ownership transfer not yet implemented

    **Workaround**:

    1. Make the intended new owner an ADMIN
    2. Give them full permissions
    3. As current OWNER, restrict your own permissions (stay as OWNER but with limited actions)
    4. Contact Junis support for manual ownership transfer if needed

    **Coming Soon**: Self-service ownership transfer feature
  </Accordion>
</AccordionGroup>

***

## API Reference for Multi-Organization Management

### List Your Organizations

**Endpoint**: `GET /api/organizations`

**Authentication**: Bearer token required

**Response**:

```json theme={null}
{
  "organizations": [
    {
      "id": "org-uuid-1234",
      "name": "Acme Marketing",
      "slug": "acme-marketing",
      "status": "ACTIVE",
      "org_type": "STANDARD",
      "role": "OWNER",
      "member_count": 12,
      "agent_count": 25,
      "created_at": "2026-01-01T00:00:00Z",
      "last_active_at": "2026-01-01T16:00:00Z"
    },
    {
      "id": "org-uuid-5678",
      "name": "Personal Workspace",
      "slug": "john-doe-personal",
      "status": "PENDING",
      "org_type": "STANDARD",
      "role": "OWNER",
      "member_count": 1,
      "agent_count": 3,
      "created_at": "2026-01-01T10:00:00Z"
    }
  ],
  "total": 2,
  "current_organization_id": "org-uuid-1234"
}
```

### Switch Organization

**Endpoint**: `POST /api/organizations/{organization_id}/switch`

**Authentication**: Bearer token required

**Response**:

```json theme={null}
{
  "message": "Switched to organization: Acme Marketing",
  "organization_id": "org-uuid-1234",
  "organization_name": "Acme Marketing",
  "new_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

**Important**: Use the `new_token` for all subsequent requests. It contains the new organization context.

### Create Organization (Programmatically)

See "Organization Creation via API" section above.

***

## What's Next?

<CardGroup cols={2}>
  <Card title="Team Management" icon="users" href="/guides/organization/team-management">
    Manage team members and permissions
  </Card>

  <Card title="Admin Dashboard" icon="gauge-high" href="/getting-started/admin-interface">
    Learn about the admin dashboard interface
  </Card>
</CardGroup>

***

## Additional Resources

* **Organization API Reference**: Full API documentation for all organization endpoints
* **Enterprise Plans**: Contact sales for custom organization limits and features
* **Migration Guide**: Moving agents between organizations (coming soon)
* **Organization Templates**: Pre-configured organization setups for common use cases

<Note>
  **Need Help with Multi-Organization Setup?** Contact Junis support at [contact@junis.ai](mailto:contact@junis.ai) or your dedicated account manager.
</Note>