Skip to content

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:

RoleDescription
OwnerFull control including billing, org deletion, and ownership transfer
AdminManage users, settings, SSO, audit logs, and reports
MemberCreate conversations, upload files, use AI features
ViewerRead-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"]
}
FieldRequiredDescription
nameYesStable identifier for the role (e.g. for API and assignment)
display_nameNoHuman-readable label shown in the UI
permissionsYesArray 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 ​

RoleDescriptionKey Permissions
Platform AdminFull platform controlAll modules, all tenants, global policies, deploy modules
Cloud AdminCross-tenant managementManage tenants, billing, compliance, deployments, platform analytics
MSP AdminManaged service providerCreate/manage sub-tenants, white-label config, reseller billing
Consumer AdminPersonal settings onlyManage personal settings and linked accounts
ObserverRead-only growth dashboardView 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

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 ​

  1. Open the Platform Admin Console (sidebar → Platform Admin)
  2. Go to the Users tab
  3. Find the user and use the Role dropdown to assign a role
  4. 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/platform

Returns all roles with their associated permissions.

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/dashboard

Content Library Permissions ​

The Content Library uses three dedicated permissions that map to organization roles:

PermissionDescriptionRoles
content_library:readBrowse, search, view, download, and bookmark content; submit feedback; create collectionsAll authenticated users with grants (Member, Viewer with grants; Admin and Owner automatically)
content_library:manageCreate and revoke grants, bulk grant, manage item flags, handle access requests, view acknowledgments, delete feedbackAdmin, Owner
content_library:auditView audit logs, usage analytics, stale content reports, and all feedbackAdmin, 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 ​

SOC 2 Type II Certified | BAA Available | HIPAA-Ready