CrewAI Enterprise: Team Collaboration and Access Control Guide

Problem: CrewAI Works Locally — But Breaks Down Across Teams

Your single-developer CrewAI setup runs fine. Then a second team member pulls the repo, uses a different API key, overwrites the shared crew config, and your production pipeline silently switches models.

This is the exact problem CrewAI Enterprise solves. It adds role-based access control (RBAC), shared crew libraries, workspace isolation, and audit logging on top of the open-source core.

You'll learn:

• How to configure workspaces and team roles in CrewAI Enterprise
• How to set per-role permissions on crews, agents, and tools
• How to share crew templates across teams without configuration drift

Time: 25 min | Difficulty: Advanced

Why Open-Source CrewAI Doesn't Scale to Teams

Open-source CrewAI is file-based and single-user by design. Every developer runs their own .env, their own crew.py, and their own tool configs. There's no concept of "who can deploy this crew" or "which teams can use this agent."

Symptoms you're hitting the ceiling:

• Two devs editing the same agents.yaml cause merge conflicts in production
• A junior dev accidentally changes the LLM from gpt-4o to gpt-3.5-turbo in a shared crew
• No audit trail for which crew ran which task and who triggered it
• Secrets like API keys live in .env files checked into git (sometimes)

CrewAI Enterprise moves crews, agents, and tools into a managed backend with a proper permissions layer.

Architecture Overview

Before diving into setup, here's the access model:

Organization
└── Workspace (e.g., "marketing-team", "eng-platform")
    ├── Members (with roles: Owner, Admin, Developer, Viewer)
    ├── Crews (versioned, with deploy permissions)
    ├── Agents (shared library or workspace-scoped)
    └── Tools (centrally managed, permission-gated)

A Workspace is the unit of isolation. Teams don't see each other's crews unless explicitly shared. Roles control what members can do within a workspace.

Solution

Step 1: Install CrewAI Enterprise CLI

# Requires Python 3.11+ and uv (recommended) or pip
uv pip install crewai[enterprise]

# Verify enterprise features are available
crewai version --enterprise

Expected output:

CrewAI 0.86.0 (Enterprise Edition)
Enterprise features: workspaces, rbac, audit-log

If it fails:

• No enterprise features → You installed the base package. Run uv pip install "crewai[enterprise]" with brackets.
• Python version error → Enterprise requires 3.11+. Check with python --version.

Step 2: Authenticate and Create Your Organization

# Opens browser for SSO login
crewai auth login

# Create the org (one-time, org admin only)
crewai org create --name "acme-corp" --plan enterprise

Expected output:

✓ Authenticated as mark@acme.com
✓ Organization "acme-corp" created
  Org ID: org_01hx...
  Dashboard: https://app.crewai.com/org/acme-corp

This org ID anchors all workspace and permission configs going forward.

Step 3: Create Workspaces Per Team

Each team gets its own workspace. Crews inside one workspace are invisible to other workspaces by default.

# Create workspaces for two teams
crewai workspace create --name "marketing-ai" --org acme-corp
crewai workspace create --name "eng-platform" --org acme-corp

# List to confirm
crewai workspace list --org acme-corp

Expected output:

WORKSPACE         ID              STATUS
marketing-ai      ws_02abc...     active
eng-platform      ws_03def...     active

Now switch into the workspace you're configuring:

crewai workspace use marketing-ai

All subsequent commands run in this workspace context until you switch.

Step 4: Configure Role-Based Access Control

CrewAI Enterprise ships with four built-in roles. Assign them per workspace member, not globally.

Invite teammates and assign roles:

# Invite a developer (can build and run, can't manage members)
crewai member invite \
  --email alice@acme.com \
  --role developer \
  --workspace marketing-ai

# Invite a stakeholder who only needs to view run history
crewai member invite \
  --email bob@acme.com \
  --role viewer \
  --workspace marketing-ai

To bulk-invite from a CSV:

# members.csv format: email,role
# alice@acme.com,developer
# bob@acme.com,viewer
crewai member import --file members.csv --workspace marketing-ai

If it fails:

• User already exists in org → The user needs to accept their org invite first before being added to a workspace.

Step 5: Define a Shared Crew with Access Policies

This is where Enterprise earns its place. You define access policies directly in crew.yaml alongside your agents and tasks.

# crew.yaml — versioned, stored in CrewAI backend
name: "content-pipeline"
version: "1.2.0"
workspace: "marketing-ai"

# Who can do what with this crew
access:
  run:
    - role: developer
    - role: admin
  edit:
    - role: admin
  deploy:
    - role: owner

agents:
  - id: researcher
    role: "Senior Research Analyst"
    goal: "Find accurate, cited information on the given topic"
    backstory: "You have 10 years of experience in market research."
    llm: gpt-4o           # pinned — no drift
    tools:
      - web_search
      - file_read

  - id: writer
    role: "Content Strategist"
    goal: "Write engaging, accurate long-form content"
    backstory: "You specialize in B2B SaaS content for technical audiences."
    llm: gpt-4o
    tools:
      - file_write

tasks:
  - id: research_task
    description: "Research {topic} and return 5 key findings with sources"
    agent: researcher
    expected_output: "Bullet list of findings, each with a URL citation"

  - id: write_task
    description: "Write a 1200-word article based on the research findings"
    agent: writer
    context:
      - research_task
    expected_output: "Full article in Markdown format"

process: sequential

Push this crew definition to the workspace:

crewai crew push --file crew.yaml --workspace marketing-ai

Expected output:

✓ Crew "content-pipeline" pushed
  Version: 1.2.0
  Workspace: marketing-ai
  Access policies applied: run(developer, admin), edit(admin), deploy(owner)

Any developer in marketing-ai can now run this crew. Nobody can change the gpt-4o model config unless they have the admin role.

Step 6: Manage Secrets Centrally (No More .env in Git)

Enterprise provides a workspace-scoped secret store. Tools and agents reference secrets by name — the actual values never touch developer machines.

# Store secrets in the workspace vault
crewai secret set OPENAI_API_KEY sk-proj-... --workspace marketing-ai
crewai secret set SERPER_API_KEY abc123... --workspace marketing-ai

# Confirm (values are masked)
crewai secret list --workspace marketing-ai

Output:

SECRET              CREATED             LAST_USED
OPENAI_API_KEY      2026-03-09          2026-03-09
SERPER_API_KEY      2026-03-09          never

In your crew.yaml, reference secrets by name — no hardcoded values:

agents:
  - id: researcher
    tools:
      - web_search:
          api_key: "${{ secrets.SERPER_API_KEY }}"

When a developer runs the crew locally via the CLI, the secret is injected at runtime from the vault. The raw key is never written to disk.

Step 7: Share Crew Templates Across Workspaces

A crew built by the platform team might be useful to marketing, sales, and support. Instead of copying crew.yaml files around, publish it as an org-level template.

# Promote a workspace crew to org-level template
crewai crew publish \
  --crew content-pipeline \
  --workspace marketing-ai \
  --scope org \
  --name "Content Research Template"

Other workspace admins can now import it:

# In the sales-team workspace
crewai crew import \
  --template "Content Research Template" \
  --workspace sales-team \
  --version 1.2.0

The imported crew is a snapshot — changes to the original template don't auto-propagate. Workspace admins control when to pull updates, preventing surprise regressions.

Step 8: Enable Audit Logging

Every crew run in Enterprise is logged with: who triggered it, which crew version ran, input/output tokens, duration, and exit status.

# View recent runs in the workspace
crewai runs list --workspace marketing-ai --limit 20

# Export audit log for compliance (CSV or JSON)
crewai runs export \
  --workspace marketing-ai \
  --from 2026-03-01 \
  --to 2026-03-09 \
  --format json \
  --output audit-march.json

Sample log entry:

{
  "run_id": "run_07xyz",
  "crew": "content-pipeline",
  "version": "1.2.0",
  "triggered_by": "alice@acme.com",
  "started_at": "2026-03-09T14:22:11Z",
  "duration_seconds": 87,
  "status": "success",
  "tokens_used": 14203,
  "input": { "topic": "AI agent frameworks 2026" }
}

This log is what your security team will ask for when auditing AI system usage.

Verification

Run through this checklist to confirm the setup is solid:

# 1. Confirm workspace members and roles
crewai member list --workspace marketing-ai

# 2. Run the crew as a developer-role user
crewai crew run content-pipeline \
  --input '{"topic": "vector databases 2026"}' \
  --workspace marketing-ai

# 3. Attempt an edit as a viewer-role user (should be rejected)
crewai crew edit content-pipeline \
  --workspace marketing-ai \
  --as bob@acme.com

You should see:

• Run succeeds for Alice (developer role)
• Edit is rejected for Bob (viewer role) with Error: insufficient permissions
• Run appears in crewai runs list with Alice's email as triggered_by

Production Considerations

Version-pin your LLMs. The single biggest source of silent regressions in shared crews is model version drift. Always specify gpt-4o-2024-11-20 or claude-opus-4-20250514, never gpt-4o or latest.

Separate workspaces for prod and staging. Mirror your marketing-ai workspace as marketing-ai-staging. Developers test in staging; only owners can deploy to prod workspaces. This maps cleanly to your existing CI/CD model.

Rotate secrets on a schedule. The vault stores secrets but doesn't rotate them. Add a GitHub Actions job (or n8n workflow) that calls crewai secret set with a fresh key every 90 days.

Watch token costs per workspace. Enterprise surfaces token usage per workspace and per crew in the dashboard. Set a monthly budget alert — a runaway agent loop in prod will hit you before your billing cycle does.

What You Learned

• CrewAI Enterprise isolates teams via workspaces — crews in one workspace are invisible to others by default
• RBAC roles (viewer, developer, admin, owner) are assigned per workspace, not globally
• Centralized secrets eliminate .env drift and keep raw API keys off developer machines
• Crew templates at org scope let platform teams publish reusable agents without copy-paste proliferation
• Every run is logged with triggering user, version, and token count — enough for a compliance audit

Limitation: Custom roles (beyond the four built-ins) require the Enterprise Plus tier. If you need granular per-crew permissions (e.g., "Alice can run crew A but not crew B"), you'll need to split workspaces or upgrade.

Tested on CrewAI 0.86.0 Enterprise, Python 3.12, Ubuntu 24.04 and macOS Sequoia 15.3