Multi-Tenant Guide

Comprehensive guide to managing client organizations, data isolation, billing, and org-scoped agent deployments.

Overview

AgenticMail Enterprise supports multi-tenancy — the ability to serve multiple client organizations from a single installation. Each organization gets its own agents, policies, knowledge base, and billing, while you maintain centralized control as the platform operator.

This is ideal for agencies, MSPs, and enterprises that deploy AI agents for multiple clients or departments.

Key Concepts

Concept	Description
Organization	A client tenant — has its own slug, agents, billing rate, and contact info
Agent Assignment	Agents are linked to organizations. An agent serves one org at a time.
User Binding	Dashboard users can be bound to an org, restricting their view to that org's data
Org Context Switcher	Admins/owners can switch between org views without logging out
Per-Agent Billing	Each org has a default rate per agent/month, with optional per-agent overrides

Architecture

The multi-tenant system works through organization-scoped data access. Here's how the layers interact:

┌─────────────────────────────────────────────┐
│              Platform Owner                  │
│  (sees all orgs, full admin access)          │
├─────────────────────────────────────────────┤
│  Org: AgenticMail        │  Org: TechStart Inc   │
│  ├── Agent: Sales Bot  │  ├── Agent: Support│
│  ├── Agent: HR Helper  │  ├── Agent: Ops    │
│  ├── Policies (scoped) │  ├── Policies      │
│  ├── Knowledge Base    │  ├── Knowledge Base│
│  └── Billing: $50/agent│  └── Billing: $75  │
├─────────────────────────────────────────────┤
│  User: alice@acme.com  │  User: bob@globex  │
│  (locked to Acme)      │  (locked to Globex)│
└─────────────────────────────────────────────┘

Managing Organizations

Creating an Organization

Go to Organizations in the dashboard
Click New Organization
Fill in the details:
- Name: Display name (e.g., "AgenticMailoration")
- Slug: URL-safe identifier, auto-generated from name (e.g., "acme-corporation")
- Contact Name & Email: Primary contact for this client
- Description: Internal notes about this organization
- Billing Rate: Monthly cost per agent (e.g., $50/agent/month)
- Currency: USD, EUR, GBP, NGN, CAD, or AUD
Click Create

Organization Lifecycle

Action	Effect
Activate/Deactivate	Toggle an org active or inactive. Inactive orgs' agents stop operating.
Edit	Update name, contact info, description, billing rate.
Delete	Permanently remove. Only allowed when no agents are assigned.

Slugs are permanent. Once created, an organization's slug cannot be changed. Choose carefully.

Agent Assignment

Agents are assigned to organizations from the organization detail view:

Click an organization card to open its detail modal
In the Agents tab, use the dropdown to select an agent
Click Assign

Assigned agents are listed with their name, email, status, and an Unassign button.

How Assignment Works

An agent can belong to one organization at a time
Assigning an agent that's already in another org will move it to the new org
Unassigned agents belong to the default (platform owner's) organization
The agent dropdown shows which agents are available and which are already assigned elsewhere

Bulk assignment: To assign multiple agents, repeat the select → assign flow. Each assignment is immediate.

User → Org Binding

Dashboard users can be bound to a specific organization via the Users page permission editor:

Bound users can only see their organization's data — agents, knowledge, billing, guardrails
Unbound users (owners and admins) can see all organizations and switch between them

Setting Up a Client User

Go to Users in the dashboard
Create or edit a user
In the Permission Editor, set their Client Organization to the appropriate org
Configure which pages they can access (e.g., give them access to Agents and Knowledge, but not Settings)
Save permissions

When this user logs in, the org switcher will be locked to their organization — they see a "Locked" badge and cannot switch to other orgs.

Permission Levels

Role	Org Switcher	Data Access
Owner	Free switching	All organizations
Admin	Free switching	All organizations
User (unbound)	Free switching	Based on page permissions
User (org-bound)	Locked to their org	Their org's data only

Org Context Switching

The Org Context Switcher appears at the top of multi-tenant-aware pages (Guardrails, Knowledge, Agents, etc.). It lets admins and owners view data as if they were in a specific organization.

How It Works

Select an organization from the dropdown to view its data
Select "My Organization" to return to the platform owner's view
The switcher shows the org's contact info when selected
When impersonating a user, an "Impersonating" badge appears

The org context is passed to all API calls on that page — agents, policies, knowledge entries, and interventions are all filtered to the selected org.

Data Isolation

Each organization's data is logically isolated:

Data Type	Isolation Method
Agents	Assigned to specific org via `client_org_id`
Policies	Scoped by `orgId` — each org has its own policy set
Knowledge Base	Partitioned by org — agents only access their org's knowledge
Agent Memory	Per-agent, inherits org scope from the agent's assignment
Interventions	Logged per org for audit trails
Billing Records	Per org, per agent, per month
Skills/Integrations	Credentials can be org-scoped or agent-scoped

Data isolation is logical, not physical. All orgs share the same database. Access control is enforced at the application layer through org ID filtering on every query.

Billing & Cost Tracking

The billing system tracks revenue (what you charge clients) against cost (token usage). Access billing from the organization detail modal's Billing & Costs tab.

Setting Rates

Default Org Rate: Set when creating the org (e.g., $50/agent/month). Applied to all agents unless overridden.
Per-Agent Rate: Override the default for specific agents. Useful when some agents use more resources than others.

Billing Dashboard

The billing tab shows:

Revenue vs. Cost chart: Monthly bar chart showing revenue (green) vs. token cost (red) with net profit/loss
Summary stats: Total revenue, total token cost, margin percentage, total tokens used
Per-agent rates: Cards showing each agent's billing rate with inline editing
Billing records table: Detailed monthly breakdown by agent — revenue, token cost, profit, token count

How Costs Are Calculated

Token costs are calculated using the model pricing configured in Settings → Models. Each agent's token usage (input + output) is multiplied by the per-million-token price for the model they used.

Monthly Revenue  = agent_count × billing_rate_per_agent
Monthly Cost     = Σ (input_tokens × input_price + output_tokens × output_price) / 1,000,000
Margin           = (Revenue - Cost) / Revenue × 100%

Knowledge Partitioning

Each organization has its own knowledge base. When you use the Org Context Switcher on the Knowledge page, you see only that org's documents and data.

Agents only access knowledge from their assigned organization
Uploading documents while viewing an org scopes them to that org
RAG (Retrieval-Augmented Generation) queries are automatically filtered by org

Shared knowledge: If you need some knowledge available to all orgs, create it under the default (owner) org and ensure cross-org agents can access it. Most deployments keep knowledge strictly partitioned.

Org-Scoped Guardrails

The Guardrails system is fully org-aware:

Policies are created per org — each client can have different behavioral rules
Onboarding tracks per-org progress — agents acknowledge their org's specific policies
Interventions are logged per org — intervention history is isolated
Rules can be org-specific — different anomaly thresholds per client

Use the Org Context Switcher on the Guardrails page to manage each org's policies independently.

Best Practices

Create orgs before agents — have the org structure in place, then assign agents to it
Use meaningful slugs — they're permanent and used in API calls. Keep them short and recognizable
Set billing rates at creation — it's easier than updating them later across many agents
Bind client users to their org — prevents accidental data leakage between tenants
Review billing monthly — check margins and adjust rates if token costs exceed revenue
Keep per-agent rate overrides documented — note why specific agents have custom rates
Deactivate before deleting — deactivate an org first, monitor for issues, then unassign agents and delete
Use org-scoped policies — don't create one-size-fits-all policies; tailor them per client
Test as the client — use the org switcher (or impersonation) to verify the client experience

Troubleshooting

Issue	Solution
User can't see org switcher	Org switcher only appears when client orgs exist. Create at least one organization.
User sees wrong org's data	Check the org switcher selection. If the user is org-bound, verify their `clientOrgId` in User permissions.
Can't delete organization	Unassign all agents first. Orgs with assigned agents cannot be deleted.
Agent not appearing in org	Verify the agent was assigned via the org detail modal. Check the agent isn't assigned to a different org.
Billing shows $0 revenue	Check that the org has a billing rate set and agents are assigned. Revenue = rate × agents.
Client user sees all orgs	The user's role is owner or admin, which overrides org binding. Set their role to "user" for org-locked access.
Org switcher shows "Locked"	This is correct — the user is bound to a specific org. Only owners/admins can switch freely.
Token costs not matching	Verify model pricing in Settings → Models. Costs are calculated using configured per-million-token prices.

Guardrails & Policies — Org-scoped policies and agent onboarding
Settings — Model pricing for billing calculations
Audit Log — Track org-related changes
Skills & Integrations — Org-scoped credentials

AgenticMail Enterprise — Multi-Tenant Guide

AgenticMail Enterprise Documentation Report an issue

Multi-Tenant Guide

On This Page

Overview

Key Concepts

Architecture

Managing Organizations

Creating an Organization

Organization Lifecycle

Agent Assignment

How Assignment Works

User → Org Binding

Setting Up a Client User

Permission Levels

Org Context Switching

How It Works

Data Isolation

Billing & Cost Tracking

Setting Rates

Billing Dashboard

How Costs Are Calculated

Knowledge Partitioning

Org-Scoped Guardrails

Best Practices

Troubleshooting

Related Pages