Appearance
Roles & Permissions
GhostAI uses a two-level role system: organization roles that control what a user can do within their organization, and platform roles that control cross-tenant administrative access.
Organization Roles
Every user in an organization has one of these roles:
| Role | Description |
|---|---|
| Owner | Full control including billing, org deletion, and ownership transfer |
| Admin | Manage users, settings, SSO, audit logs, and reports |
| Member | Create conversations, upload files, use AI features |
| Viewer | Read-only access to conversations and reports |
Organization roles are managed from Admin Dashboard → Users within each organization.
Custom Role Builder
Beyond the four built-in organization roles, custom roles let you define org-specific roles with an explicit permission list. Built-in roles (Owner, Admin, Member, Viewer) are fixed templates with predefined capabilities; custom roles are created per organization and named by you, with permissions chosen from the same permission strings the platform uses elsewhere.
- Create a custom role:
POST /api/admin/roles - Who can call it: Owner only. Organization Admin is not sufficient—creating roles is reserved for owners.
- Body:
json
{
"name": "legal_reviewer",
"display_name": "Legal Reviewer",
"permissions": ["content_library:read", "content_library:manage"]
}| Field | Required | Description |
|---|---|---|
name | Yes | Stable identifier for the role (e.g. for API and assignment) |
display_name | No | Human-readable label shown in the UI |
permissions | Yes | Array of permission strings granted to this role |
Platform Roles
Platform roles provide cross-tenant administrative access. They are assigned from Platform Admin Console → Users or Admins.
Role Hierarchy
Platform Admin (highest)
└── Cloud Admin
└── MSP Admin
└── Consumer Admin
└── Observer (lowest, read-only)Role Details
| Role | Description | Key Permissions |
|---|---|---|
| Platform Admin | Full platform control | All modules, all tenants, global policies, deploy modules |
| Cloud Admin | Cross-tenant management | Manage tenants, billing, compliance, deployments, platform analytics |
| MSP Admin | Managed service provider | Create/manage sub-tenants, white-label config, reseller billing |
| Consumer Admin | Personal settings only | Manage personal settings and linked accounts |
| Observer | Read-only growth dashboard | View platform analytics and growth metrics |
Platform Admin
Platform Admins have unrestricted access to every feature in the platform:
- Deploy and configure modules
- Manage global policies
- View and manage all tenants and billing
- Promote/demote other users to any role
- Access all Platform Admin Console sections
Cloud Admin
Cloud Admins manage the operational side of the platform:
- Create, update, and suspend tenants
- View all billing and compliance data
- Export compliance reports
- Manage deployments
- View platform-wide analytics
MSP Admin
MSP (Managed Service Provider) Admins manage a portfolio of sub-tenants:
- Create and manage sub-tenants under their MSP organization
- Configure white-label branding
- Set up and view reseller billing
- Delegate support to sub-tenants
- View sub-tenant analytics
Consumer Admin
Consumer Admins have minimal access for personal use:
- Read and update personal settings
- Manage linked accounts
Observer
Observers have read-only access to the Growth Dashboard. This role is designed for VCs, board members, investors, and external stakeholders who need visibility into platform adoption and growth without any administrative capabilities.
- View the Growth Dashboard (signups, MRR, K-factor, conversion rates, tier distribution)
- Access via sidebar "Growth Dashboard" button or via a shareable link
Observers cannot:
- Access the Platform Admin Console
- Modify any settings, users, or organizations
- View individual user data or PII
Share Links
Platform Admins can generate time-limited shareable links that give anyone access to the Growth Dashboard without requiring a GhostAI account. These are ideal for quick VC demos and board meeting prep.
- Generate from Platform Admin Console → Analytics → Observer Dashboard Share Links section
- Each link has a label, expiry date, and access count
- Links can be revoked at any time
- Accessing a share link goes to
/observer?token=...
Assigning Roles
From the Platform Admin Console
- Open the Platform Admin Console (sidebar → Platform Admin)
- Go to the Users tab
- Find the user and use the Role dropdown to assign a role
- Or click View on a user and change their role in the detail modal
Changes take effect immediately. The Admins section updates automatically to reflect role changes.
Initial Admin Setup via Environment Variables
Configure initial admin accounts using environment variables:
bash
# Used for initial admin setup (comma-separated for multiple emails)
PLATFORM_ADMIN_EMAIL="admin@example.com,admin2@example.com"
# Used for initial admin setup (comma-separated for multiple emails)
CLOUD_ADMIN_EMAIL="cloud@example.com,cloud2@example.com"Use the manual assignment method above for immediate effect.
From the Admins Tab
Admins in the Platform Admin Console shows all users grouped by role. From here you can:
- Promote a Cloud Admin to Platform Admin
- Promote an MSP Admin to Cloud Admin
- Demote any admin (removes their role)
API Reference
Set Platform Role
bash
POST /api/platform-admin/users/{user_id}/platform-role
Content-Type: application/json
{
"platform_role": "cloud_admin"
}Available values: platform_admin, cloud_admin, msp_admin, consumer_admin, observer, or null to remove.
List Users by Role
bash
GET /api/platform-admin/users/by-platform-role/{role}List Available Roles
bash
GET /api/platform-admin/roles/platformReturns all roles with their associated permissions.
Observer Share Links (API)
bash
# Create a share token (platform admin only)
POST /api/observer/share-tokens
Content-Type: application/json
{
"label": "Sequoia Q1 Review",
"expires_in_days": 30
}
# List all share tokens
GET /api/observer/share-tokens
# Revoke a share token
DELETE /api/observer/share-tokens/{token_id}
# Access the dashboard (with share token)
GET /api/observer/dashboard?token=TOKEN_VALUE
# Access the dashboard (authenticated observer+ role)
GET /api/observer/dashboardContent Library Permissions
The Content Library uses three dedicated permissions that map to organization roles:
| Permission | Description | Roles |
|---|---|---|
content_library:read | Browse, search, view, download, and bookmark content; submit feedback; create collections | All authenticated users with grants (Member, Viewer with grants; Admin and Owner automatically) |
content_library:manage | Create and revoke grants, bulk grant, manage item flags, handle access requests, view acknowledgments, delete feedback | Admin, Owner |
content_library:audit | View audit logs, usage analytics, stale content reports, and all feedback | Admin, Owner |
Admins and Owners bypass the grant system entirely and can access all categories and items. Members and Viewers require explicit category-level or item-level grants, which can optionally have an expiration date.
For details on the access control model, grant templates, and API endpoints, see Content Library.
Next Steps
- Dashboards & Analytics — Overview of all dashboards
- AI Audit Logs — View admin action audit trail
- Team Invitations — Manage team membership
- Content Library — Document library access control and features