Global Admin Setup

Self-Hosting Documentation Access

This section requires a password to access. Interested in self-hosting? Contact sales to learn more.

Password:

Access Documentation

Self-Hosting Documentation Access Granted Logout

Global administrators have platform-wide access and can manage all organizations, users, and system-level configurations in your self-hosted LlamaCloud deployment. This guide covers how to set up and manage global admin access.

Overview

The global admin feature provides:

• Cross-organization visibility: Inspect all user-organization memberships across the platform
• Admin user management: Add and remove global admin privileges
• System-wide access: Bypass organization-level restrictions for troubleshooting and support
• User support capabilities: Help users with organization access and membership issues

Bootstrap Initial Global Admins

Choose the appropriate approach based on your deployment needs:

Approach 1: Grant Global Admin to First User (Simplest)

Use this approach when you want to automatically grant admin access to the very first user in your deployment without configuring any email lists.

When to Use

• Fresh deployment with no existing admins
• You want the earliest user (by creation time) to become the first admin
• Simplest setup - no environment variables needed

Setup Steps

1. Deploy LlamaCloud without any special global admin configuration
2. Ensure at least one user has logged in (this creates the user_organization record)
3. Bootstrap the first admin by calling the sync endpoint:

curl -X POST "https://your-llamacloud-domain/api/internal/permissions/sync-global-admins?earliest_email=true"

Tip

The earliest_email=true parameter finds the user with the earliest created_at timestamp in the user_organization table and grants them admin privileges. This helps bootstrap the admin system when no admins exist yet.

Approach 2: Specify Admin Users via Environment Variable

Use this approach when you want to explicitly control which users become global admins (e.g. if first user is not the desired initial global admin).

When to Use

• You want to grant admin access to specific users by email address
• More controlled admin assignment
• Adding additional admins after initial setup

Setup Steps

1. Configure admin emails in your values.yaml file:

backend:
  extraEnvVariables:
    - name: GLOBAL_ADMIN_EMAILS
      value: "admin1@yourcompany.com,admin2@yourcompany.com,admin3@yourcompany.com"

2. Deploy the updated configuration to your cluster

3. Sync the permissions by calling the API endpoint:

curl -X POST "https://your-llamacloud-domain/api/internal/permissions/sync-global-admins"

• Email requirements: Use comma-separated email addresses with no spaces
• User prerequisite: Listed users must have logged into the platform at least once
• Idempotent: Safe to run multiple times - won’t create duplicate permissions

Approach 3: Treat an Email Pattern as Global Admin (Interim Override)

Use this approach as a temporary override when everyone whose email matches a pattern, such as your company domain, should act as a global admin without granting each one.

1. Configure the pattern in your values.yaml file:

backend:
  extraEnvVariables:
    - name: ALLOWED_GLOBAL_ADMIN_REGEX
      value: '[^@]+@yourcompany\.com'

2. Deploy the updated configuration to your cluster

Matching users have global admin access on their requests as soon as the backend restarts. No sync call is needed, and nothing is stored: remove the variable and redeploy to end the override.

• Whole-email match: The pattern must match the entire email address, ignoring case. [^@]+@yourcompany\.com does not match someone@yourcompany.com.example.net.
• Anchor on the domain: A loose pattern such as .*yourcompany.* makes any address containing that text an admin. Only use this with an identity provider that verifies email addresses.
• Not listed as admins: Because no permission is stored, these users don’t appear in the Admin Management tab. To make someone a lasting admin, use Approach 2 or the UI.

Manage Additional Global Admins via UI

Once you have at least one global admin, you can manage additional admins through the web interface.

Access the Global Admin UI

1. Log in to your LlamaCloud instance with a global admin account
2. Navigate to /global-admin in your browser
3. You’ll see tabs for Users and Admin Management

Add New Global Admins

1. Go to the Admin Management tab
2. Click Add Admin
3. Enter the User ID (not email) of the user you want to promote
4. Click Add Admin

The manual method requires the User ID (UUID), not the email address. You can find User IDs by searching in the Users tab first.

Global Admin Permission Levels

• Global admin UI access: Can view and manage all user-organization relationships
• Admin user management: Can add and remove other global admin users
• RBAC permissions: Can create and delete RBAC permissions via API
• Cross-organization API access: Can call all existing APIs across all organizations when using user-scoped API keys
• Bypasses organization restrictions: Full platform access via API

For cross-organization API access, you must use user-scoped API keys, not project-scoped keys.

API Reference

Sync Global Admins

POST /api/internal/permissions/sync-global-admins
POST /api/internal/permissions/sync-global-admins?earliest_email=true

Synchronizes global admin permissions from the GLOBAL_ADMIN_EMAILS environment variable. Optionally includes the earliest user (by creation time) for bootstrap scenarios.

Parameters:

• earliest_email (boolean, optional): If true, automatically grants admin privileges to the earliest user by created_at timestamp in the user_organization table. Useful for initial deployment setup.

Response:

{
  "added": ["admin1@company.com", "earliest-user@company.com"],
  "skipped": ["admin2@company.com"],
  "errors": ["nonexistent@company.com"]
}

Notes:

• Rate limited to 2 requests per 30 seconds
• Idempotent - safe to run multiple times
• Creates admin permissions for all processed users
• Both email list and earliest user receive the same permission level

Manage RBAC Permissions

GET    /api/permissions?target_type=global&relationship=admin
POST   /api/permissions
DELETE /api/permissions/{permission_id}

Create, read, and delete global admin permissions.