Platform Administration

Overview

Platform administrators with the super_admin role get access to business intelligence tools directly in the chat interface. The AI agent automatically detects admin queries and uses the right tools — no separate dashboard or UI needed.

Super Admin Role

The super_admin role is a Better Auth organization role that grants access to:

• Business intelligence tools in the AI agent (signups, subscriptions, trials, credits)
• Mastra Studio access (same as developer role)
• All standard organization permissions (billing, members, settings)

Assigning the Role

The super_admin role cannot be assigned from the web UI — it's internal only. Assign it directly in the auth database:

UPDATE member SET role = 'super_admin'
WHERE user_id = '<user-id>';

Or via the Turso HTTP API:

curl -X POST "${AUTH_DATABASE_URL}/v2/pipeline" \
  -H "Authorization: Bearer ${AUTH_DATABASE_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"requests": [
    {"type": "execute", "stmt": {"sql": "UPDATE member SET role = '\''super_admin'\'' WHERE user_id = '\''<user-id>'\''"}},
    {"type": "close"}
  ]}'

After updating, the user must log out and back in for the new role to take effect in their JWT.

What You Can Ask

Once you have the super_admin role, ask these questions in the normal chat interface:

Business Activity

Digest Email

The digest email is sent to all addresses configured in ADMIN_NOTIFICATION_EMAILS.

Agent Tools

Two tools power the admin capabilities:

getBusinessEvents

Queries the platform for business activity. Returns:

• Summary counts: new users, new orgs, subscription upgrades, trial activations, trial conversions, credit purchases
• Recent events: detailed list with org names, user emails, plan info, and timestamps

Supports filtering by period (24h, 7d, 30d) and event type (signups, subscriptions, credits, or all).

sendBusinessDigest

Triggers a digest email with:

• Summary table of all business metrics for the period
• List of recent signups with email, name, and organization
• Sent via Resend to all ADMIN_NOTIFICATION_EMAILS recipients

Configuration

Environment Variable

Add ADMIN_NOTIFICATION_EMAILS to your secrets file (scripts/env/.env.dev-secrets):

ADMIN_NOTIFICATION_EMAILS=admin@example.com,cto@example.com

This gets pushed to the API worker by scripts/env/setup-dev-secrets.sh. Multiple recipients are comma-separated.

Prerequisites

• RESEND_API_KEY must be configured (email sending)
• ADMIN_NOTIFICATION_EMAILS must have at least one email address
• The requesting user must have the super_admin role in Better Auth

Architecture

User (super_admin) ──chat──> Assistant Agent
                                  │
                          ┌───────┴───────┐
                          │ role check    │
                          │ super_admin?  │
                          └───────┬───────┘
                                  │ yes → admin tools available
                                  ▼
                          getBusinessEvents
                          sendBusinessDigest
                                  │
                                  ▼
                          API Service (/admin/events/*)
                                  │
                          ┌───────┴───────┐
                          │ Existing DB   │
                          │ tables:       │
                          │ - users       │
                          │ - orgs        │
                          │ - subs        │
                          │ - trials      │
                          │ - audit_log   │
                          └───────────────┘

The tools are conditionally registered on the assistant agent based on the user's JWT role. Non-super-admin users simply don't have access to these tools — the agent will tell them they need super_admin access if they ask.

No new database tables were added. All queries run against existing tables (users, organizations, subscriptions, trial_history, audit_log).