> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecrew.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspaces & Environments

> Organize teams, billing, and deployment environments

# Workspaces & Environments

Workspaces provide the organizational structure for managing teams, billing, and multiple Crews across development, staging, and production environments.

## Workspace Hierarchy

```
Organization
└── Workspace (Billing + Team Members)
    ├── Crew (Production)
    │   ├── Agents
    │   ├── Knowledge Base
    │   └── Integrations
    ├── Crew (Staging)
    └── Crew (Development)
```

## Workspaces

A Workspace is the top-level container that controls:

* **Billing** — All usage charges roll up to the Workspace
* **Team access** — Users are invited to Workspaces, not individual Crews
* **API keys** — Authentication credentials are scoped to Workspaces
* **Limits** — Rate limits and quotas apply at the Workspace level

### Creating a Workspace

<Steps>
  <Step title="Sign Up">
    Create an account at [app.usecrew.ai](https://app.usecrew.ai)
  </Step>

  <Step title="Name Your Workspace">
    Choose a name that represents your organization or project
  </Step>

  <Step title="Select Plan">
    Choose a billing plan that matches your expected usage
  </Step>

  <Step title="Invite Team">
    Add team members with appropriate roles
  </Step>
</Steps>

### Workspace Roles

| Role   | Permissions                                      |
| ------ | ------------------------------------------------ |
| Owner  | Full access, billing, delete workspace           |
| Admin  | Manage Crews, agents, integrations, invite users |
| Member | View and edit Crews, cannot manage billing       |
| Viewer | Read-only access to dashboards and logs          |

## Environments

Environments help you separate development, testing, and production workloads.

### Recommended Setup

| Environment | Purpose                           | Data                 |
| ----------- | --------------------------------- | -------------------- |
| Development | Building and testing new features | Synthetic/test data  |
| Staging     | Pre-production validation         | Production-like data |
| Production  | Live customer traffic             | Real data            |

### Environment Isolation

Each environment (Crew) maintains separate:

* Agent configurations
* Knowledge bases
* Phone numbers and channels
* Webhook endpoints
* Analytics and logs

<Warning>
  Production Crews should never share phone numbers or integrations with development or staging environments.
</Warning>

### Promoting Between Environments

To promote changes from staging to production:

<Steps>
  <Step title="Export Configuration">
    Export your staging Crew's agent and pathway configurations
  </Step>

  <Step title="Review Changes">
    Compare exported config against production
  </Step>

  <Step title="Import to Production">
    Import the validated configuration to your production Crew
  </Step>

  <Step title="Verify">
    Test key flows in production with monitoring enabled
  </Step>
</Steps>

## Multi-Tenant Architectures

For platforms serving multiple clients:

### Option 1: Workspace per Client

```
Platform Organization
├── Workspace: Client A
│   └── Crew: Production
├── Workspace: Client B
│   └── Crew: Production
└── Workspace: Client C
    └── Crew: Production
```

**Pros:** Complete isolation, separate billing, independent access control
**Cons:** More overhead to manage

### Option 2: Single Workspace, Crew per Client

```
Platform Workspace
├── Crew: Client A
├── Crew: Client B
└── Crew: Client C
```

**Pros:** Centralized management, shared team access
**Cons:** Shared billing, less isolation

## API Keys and Environments

API keys are scoped to Workspaces. For environment separation:

```bash theme={null}
# Development
CREW_API_KEY=crew_dev_xxxxxxxxxxxx

# Production
CREW_API_KEY=crew_prod_xxxxxxxxxxxx
```

<Tip>
  Create separate API keys for each environment and rotate them regularly.
</Tip>

## Best Practices

* **Never test in production** — Always use development or staging Crews
* **Mirror production** — Keep staging as close to production as possible
* **Document changes** — Track what's promoted and when
* **Use descriptive names** — `Acme Corp - Production` is better than `prod`
* **Audit access** — Regularly review who has access to production

## Next Steps

* [Knowledge Base](/core-concepts/knowledge-base) — Populate your Crews with information
* [API Overview](/developer/api-overview) — Authenticate and interact programmatically
* [SSO](/enterprise/sso) — Enterprise identity management