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

# Super Admin Guide

> Platform administration — manage organizations, plans, billing, and system health.

# Super Admin Guide

The Kaanha AI Super Admin portal is for internal platform operations. It is accessible only to users in the `default` organization with the `OWNER` role, on the `superadmin.kaanha.ai` subdomain.

## Accessing the Admin Portal

**Login**: Visit [app.kaanha.ai/login](https://app.kaanha.ai/login) and log in with your super admin credentials. You'll be automatically redirected to `/admin` (regular users go to `/dashboard`).

***

## Admin Dashboard

The main admin dashboard at `/admin` shows:

* **MRR / ARR** with month-over-month comparison deltas
* **Active Organizations** by plan
* **New Signups** this month
* **Churn Alerts** — orgs with declining health
* **60-second auto-refresh** (toggle ON/OFF)

***

## Organization Management

### Viewing All Organizations

`/admin/organizations` — Full list with:

* Health indicators (green/yellow/red dots based on login recency, message activity, WA connection)
* Lifecycle stages (trial / onboarding / active / at\_risk / churned)
* Filter by: plan, status, connection type, lifecycle
* Search by name, slug, or billing email
* CSV export
* Bulk actions (suspend/export selected orgs)

### Organization Detail

Click any org to open the tabbed detail view (`/admin/organizations/[id]`):

| Tab          | Contents                                                 |
| ------------ | -------------------------------------------------------- |
| **Overview** | Stats, subscription, action buttons, admin notes         |
| **Features** | Per-org feature flag overrides (see Feature Flags below) |
| **Users**    | All users with Reset Password + Disable MFA actions      |
| **Usage**    | 6-month message volume chart                             |
| **Audit**    | Last 50 audit log entries with color-coded action types  |
| **Activity** | Timeline of recent messages, logins, conversations       |
| **Reseller** | White-label grant/revoke + branding fields               |

### Admin Actions (Overview Tab)

| Action                  | Description                                       |
| ----------------------- | ------------------------------------------------- |
| **Suspend / Activate**  | Disable or re-enable an organization              |
| **Change Plan**         | Assign Free / Starter / Pro / Enterprise directly |
| **Grant Complimentary** | Give any plan free for N days (auto-expires)      |
| **Extend Trial**        | Add more days to trial period                     |
| **Update Limits**       | Override contact, message, and agent limits       |
| **Send Email**          | Send a direct email to all OWNER/ADMIN users      |
| **Impersonate**         | View read-only snapshot of org data               |
| **Grant White Label**   | Enable custom branding for resellers              |

### User Admin Actions (Users Tab)

Per-user actions in the Users tab:

* **Reset PW**: Set a new password for a user (min 6 chars — note this is a lower bar than the 8-character-plus-complexity policy enforced on self-service signup/reset). Resets lockout and failed attempts.
* **Disable MFA**: Remove 2-factor authentication for a user (use if they lose access to their authenticator).

***

## Feature Flags

Each organization has individual feature flags that override the plan defaults. Common flags:

| Flag             | Default | What it controls                                   |
| ---------------- | ------- | -------------------------------------------------- |
| `voiceAgents`    | OFF     | Voice AI sidebar, pages, and API routes            |
| `voicePremium`   | OFF     | ElevenLabs TTS for voice agents                    |
| `multiAgent`     | OFF     | Multi-agent orchestration (Lead/Helper delegation) |
| `askAiGrounding` | OFF     | `groundingHits` field on `/api/ask` responses      |
| `whiteLabel`     | OFF     | Custom domain branding + "Powered by" toggle       |
| `mcp`            | Varies  | MCP server access                                  |

Toggle any flag on the org's **Features** tab. Changes take effect immediately — no redeploy needed.

***

## Plan Management

`/admin/plans` — View and edit the official plans:

### Active Plans

| Plan           | Monthly       | Annual   | Notes                                                                       |
| -------------- | ------------- | -------- | --------------------------------------------------------------------------- |
| **Free**       | \$0           | —        | 500 contacts, 1 user, no AI                                                 |
| **Starter**    | \$19          | \$190/yr | 5,000 contacts, 3 users, no AI                                              |
| **Pro**        | \$49          | \$490/yr | 25,000 contacts, 10 team members, 10,000 AI credits/mo                      |
| **Premium**    | \$99          | —        | Unlimited contacts + users, 50,000 AI credits/mo, white-label + B2B modules |
| **Enterprise** | Contact sales | —        | Custom limits, admin-assigned only                                          |

### Tier Matrix Editor

`/admin/tier-matrix` — Drag-and-drop editor for the feature-to-plan mapping. Changes to this matrix update `PricingPlan.features` JSON and affect which features are gated behind which plan for all future signups. Does not retroactively change existing org subscriptions.

### Creating Custom Plans

Click **Create Custom Plan** to build a plan for a specific enterprise customer:

1. Set an internal name (e.g., `custom_acme_corp`)
2. Set display name, description, and pricing
3. Set limits (contacts, AI agents, team members)
4. Custom plans get all Pro features enabled by default
5. Assign to org via **Change Plan** action

Custom plans are admin-assigned only — customers cannot self-select them.

***

## Revenue & Analytics

`/admin/revenue` — Financial overview:

* MRR by plan
* **MRR Waterfall Chart** (New / Expansion / Contraction / Churn per month)
* Upcoming renewals
* Invoice list with search and status filter

`/admin/analytics` — Platform-wide metrics:

* Daily message volume across all orgs
* Top organizations by activity
* AI usage (token consumption)
* CSAT summary

`/admin/insights` — Growth intelligence:

* **Signup Funnel** — Signed Up → Verified → WA Connected → First Message → First Broadcast
* **Cohort Retention** — Monthly cohorts with M+0 through M+3 retention
* **Org Health Scores** — 0-100 score per org, sorted worst first
* **MRR Movement** — 6-month new vs churned MRR
* **Webhook Health** — 24h delivery success rate
* **Error Tracking** — Top WhatsApp errors by frequency
* **API Usage** — Top orgs by API call volume
* **Multi-Agent Delegations** — Per-org delegation counts and depth usage (sourced from `/api/admin/delegations`)

***

## System Health

`/admin/system` — Infrastructure status:

* Database connectivity and response time
* Broadcast queue stats (waiting / active / completed / failed)
* Error rates from WAErrorLog
* Deployment info

***

## System Banners

Broadcast announcements to all platform users:

1. Go to **Admin → System → Banners**
2. Click **Create Banner**
3. Set message, type (info/warning/maintenance/success), and optional expiry
4. Toggle active

Banners appear at the top of the app for all users until dismissed or expired.

***

## Incidents

`/admin/system → Incidents` — Post public status-page incidents visible at `status.kaanha.ai`:

* Set status (investigating / identified / monitoring / resolved)
* Set impact level (none / minor / major / critical)
* List affected services
* Incidents auto-resolve at `resolvedAt`

***

## Support Tickets

`/admin/support` — Internal support ticket queue:

* Tickets created via the public `/support` portal or the in-app support form
* Each ticket has a thread of messages between the user and the support team
* Internal notes (hidden from users) can be added to any ticket
* `isInternal: true` messages are only visible in the admin portal

Registered **Support Apps** (`/admin/support → Apps`) allow external tools to create tickets via API using a `sa_` prefixed key.

***

## Platform API Keys

`/admin/platform-keys` — Manage the platform-wide provider credentials that power AI and voice for every organization (OpenAI, Anthropic, Sarvam, Deepgram, ElevenLabs, and others). These are the keys tenants run on by default — separate from any per-org BYOK credentials.

`/admin/api-keys` — Manage platform-level API keys used for Kaanha AI's own service-to-service and external integrations, distinct from the per-org `wsk_`-prefixed keys organizations generate for their own REST API / MCP access.

***

## All Platform Users

`/admin/users` — A top-level, cross-organization list of every user account on the platform (not scoped to one org, unlike the Users tab inside an organization's detail view). Useful for looking up a user by email when you don't already know which org they belong to.

***

## Admin Team Management

`/admin/settings → Admin Team` — Manage super admin access:

* View all admins with MFA status and last login
* **Invite Admin**: Creates a new user in the default org with OWNER role
* **Remove Admin**: Cannot remove yourself or the last admin

***

## Audit Log

`/admin/audit-log` — Global audit trail across all organizations:

* Filter by organization, action type, date range
* Shows admin actions, user logins, data operations, webhook HMAC failures, SIP credential events
* 365-day retention policy