Organizations

Multi-tenant client management with billing, agent assignment, and revenue tracking

Overview

The Organizations page (OrganizationsPage) provides full CRUD management for client organizations in a multi-tenant AgenticMail deployment. Organizations act as logical boundaries for agent assignment, knowledge base isolation, billing, and access control. Each organization has a unique slug, contact information, billing configuration, and a set of assigned agents.

How It Works

1. Create an organization — Provide a name (auto-generates a URL-safe slug), contact details, description, and optional billing rate per agent per month.
2. Assign agents — Open the organization detail view and assign existing agents to it. Agents can be reassigned from other orgs.
3. Set billing rates — Configure a default per-agent monthly rate, or set custom rates per agent.
4. Monitor revenue — The billing tab shows revenue vs. token cost charts, margin calculations, and per-agent breakdowns.
5. Manage lifecycle — Activate, deactivate, or delete organizations as needed.

Key Concepts

Organization Slug

A URL-safe identifier auto-generated from the organization name (e.g., "AgenticMail" → agenticmail). Slugs are immutable after creation and used throughout the system for routing and identification. You can manually edit the slug during creation.

Active vs. Inactive

Organizations can be toggled active/inactive. Deactivating an organization effectively suspends all linked agents. The toggle endpoint is POST /api/organizations/{id}/toggle.

Agent Assignment

Agents are assigned to organizations via POST /api/agents/{id}/assign-org. An agent can belong to only one organization at a time. Assigning an agent that's currently in another org will move it. Unassigning returns the agent to the default (internal) org.

Creating Organizations

Form Fields

POST /api/organizations
Content-Type: application/json

{
  "name": "AgenticMail",
  "slug": "agenticmail",
  "contact_name": "Ope Olatunji",
  "contact_email": "ope@agenticmail.com",
  "description": "Enterprise client — Q1 2026 onboarding",
  "billing_rate_per_agent": 99.00,
  "currency": "USD"
}

Detail View

Clicking an organization card opens a detail modal with two tabs:

Agents Tab

• Linked agents list — Shows all agents assigned to this org with name, email, status badge, and an "Unassign" button
• Assign agent dropdown — Lists all agents not currently in this org (including those in other orgs, labeled accordingly)
• Status indicators — Active (green), Running (green), Suspended (yellow), Archived (gray)

Billing Tab

• Revenue vs Cost chart — Bar chart showing monthly revenue (green) and token cost (red) side by side
• Summary stats — Total revenue, token cost, margin percentage, total tokens
• Per-agent billing rates — Editable rate inputs for each agent (blank = uses org default)
• Billing records table — Detailed monthly breakdown per agent: revenue, token cost, profit, tokens used

Billing & Revenue Tracking

Billing data is loaded from two endpoints:

• GET /api/organizations/{id}/billing-summary — Monthly aggregated revenue, cost, and token counts
• GET /api/organizations/{id}/billing — Individual billing records per agent per month

Custom per-agent rates are saved via PATCH /api/agents/{id} with a billingRate field. The effective rate for an agent is: custom rate if set, otherwise the org's default rate.

API Reference

Best Practices

• One org per client — Create a separate organization for each client to maintain data isolation and independent billing.
• Set billing rates early — Configure rates before agents start processing tasks to ensure accurate revenue tracking from day one.
• Use custom per-agent rates — Premium agents (e.g., with expensive models) should have higher billing rates to maintain margins.
• Deactivate before deleting — Deactivate an organization first to confirm no critical workflows depend on it. Delete only when agent count is zero.
• Monitor margins monthly — The billing tab's revenue vs. cost chart quickly reveals whether you're pricing correctly.
• Slugs are permanent — Choose meaningful slugs during creation. They cannot be changed after the fact.

Troubleshooting