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

# Workspaces

> Isolate environments, teams, and data with full multi-tenancy.

Workspaces are the fundamental unit of isolation in MetrixLLM. Everything you configure — API keys, routing rules, guardrails, provider credentials, and request logs — belongs strictly to a single workspace. No data crosses workspace boundaries.

## Overview

Each workspace is an independent environment with its own:

* **Provider credentials** (OpenAI, Anthropic, Google, etc.)
* **API keys** for authenticating requests
* **Routing rules and model fallback chains**
* **Guardrails, budgets, and rate limits**
* **Request logs and analytics**
* **Team members and roles**
* **Billing and credit balance**

Workspaces are mapped to a [plan tier](/docs/billing) (Free, Pro, Team, or Enterprise) which controls feature access and usage limits.

## Multi-environment setup

The recommended pattern is to map Workspaces directly to your deployment environments:

| Workspace       | Purpose                | Typical Config                               |
| --------------- | ---------------------- | -------------------------------------------- |
| **Development** | Local engineering use  | Strict budget caps, short log retention      |
| **Staging**     | CI/CD pipelines and QA | Mirror production routing, lower limits      |
| **Production**  | Live user traffic      | Full fallback chains, guardrails, monitoring |

Because data is isolated, an engineer viewing the `Development` workspace logs will never accidentally see a `Production` user's prompt payload.

## Creating a workspace

<Steps>
  <Step title="Navigate to Workspaces">
    Click the workspace dropdown at the top of the left sidebar in the dashboard, then select **Create Workspace**.
  </Step>

  <Step title="Enter workspace name">
    Provide a name (minimum 2 characters). Optionally enter your first and last name to populate your user profile.
  </Step>

  <Step title="Start configuring">
    You are automatically assigned the **Owner** role. From here you can add provider keys, create API keys, and invite team members.
  </Step>
</Steps>

<Note>
  Each new workspace starts on the **Free** tier with 25,000 requests/month. Upgrade via **Settings → Billing** to unlock higher limits and features.
</Note>

## Switching workspaces

Use the dropdown menu at the top of the left sidebar in the dashboard to switch between workspaces. The active workspace determines which API keys, logs, and settings are displayed.

## Member roles and permissions

Workspaces support four built-in roles:

| Role        | Permissions                                                                          |
| ----------- | ------------------------------------------------------------------------------------ |
| **Owner**   | Full control. Can manage billing, delete workspace, modify roles. Cannot be removed. |
| **Admin**   | Manage settings, invite/remove members (except other admins), view audit logs.       |
| **Billing** | View and manage billing settings and credits.                                        |
| **Viewer**  | Read-only access to logs, analytics, and settings.                                   |

<Note>
  **Team** and **Enterprise** plans unlock **Custom Roles** with granular permission strings (e.g. `logs:read`, `prompts:write`, `guardrails:read`).
</Note>

### Inviting members

<Steps>
  <Step title="Open Members page">
    Navigate to your workspace → **Settings → Members**.
  </Step>

  <Step title="Send invitation">
    Click **Invite Member**, enter their email, and select a role (`admin`, `billing`, or `viewer`).
  </Step>

  <Step title="Invitee accepts">
    The invitee receives an email with a link valid for **7 days**. They must create an account or log in to accept.
  </Step>
</Steps>

<Warning>
  Seat limits are enforced based on your plan tier. Free plans are limited to 3 seats. Pro, Team, and Enterprise have unlimited seats.
</Warning>

### Removing members

* **Owners** can remove any member except themselves.
* **Admins** can remove viewers and billing members only.
* To leave a workspace, use **Leave Workspace** (owners must transfer ownership first).

## Workspace settings

Only owners and admins can modify workspace settings. Key configurable options:

| Setting              | Description                                     | Plan Requirement |
| -------------------- | ----------------------------------------------- | ---------------- |
| **Data Retention**   | Toggle request log storage                      | All tiers        |
| **Smart Caching**    | Enable semantic response caching                | Pro+             |
| **IP Allowlist**     | Restrict gateway access to specific CIDR ranges | Pro+             |
| **Fallback Routing** | Enable automatic provider fallback on failure   | All tiers        |
| **Workspace Name**   | Display name for the workspace                  | All tiers        |

### Updating settings via API

```bash theme={null}
curl -X PATCH https://api.metrixllm.com/api/workspaces/{workspaceId}/settings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "isCacheEnabled": true,
    "isIpAllowlistEnabled": true,
    "allowedIps": [
      {"cidr": "10.0.0.0/8", "label": "Internal network", "enabled": true}
    ]
  }'
```

Setting changes are propagated to the edge gateway via NATS in real time.

## Model access control

You can control which models are available in your workspace. By default, all enabled models are accessible. To restrict access:

1. Navigate to **Settings → Models** in your workspace.
2. Toggle individual models on or off.
3. Only **disabled** models are stored — all others default to enabled.

The gateway checks this list on every request and rejects calls to disabled models.

## Billing and credits

Each workspace maintains its own credit balance:

* **Credits Allocated**: Total credits deposited or purchased.
* **Balance**: `creditsAllocated - totalSpent` (cannot go below zero).

### Autopay

Enable autopay to automatically recharge your workspace when the balance drops below a threshold:

```bash theme={null}
curl -X PUT https://api.metrixllm.com/api/workspaces/{workspaceId}/billing/settings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "autopayEnabled": true,
    "autopayThreshold": 10,
    "autopayAmount": 50
  }'
```

### Budget alerts

Configure email alerts when spending reaches a threshold:

```bash theme={null}
curl -X PUT https://api.metrixllm.com/api/workspaces/{workspaceId}/billing/settings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "budgetAlertEnabled": true,
    "budgetAlertThreshold": 100,
    "budgetAlertEmails": ["billing@acme.com", "cto@acme.com"]
  }'
```

## Deleting a workspace

Only the **owner** can delete a workspace. Deletion is soft (marked as deleted, not removed from the database):

```bash theme={null}
curl -X DELETE https://api.metrixllm.com/api/workspaces/{workspaceId} \
  -H "Authorization: Bearer YOUR_TOKEN"
```

<Warning>
  Workspace deletion is permanent after a grace period. All API keys, logs, and configurations will be lost. Export any data you need before deleting.
</Warning>

## Audit logging

Team and Enterprise workspaces record an audit log of all significant actions:

* Member invites, removals, and role changes
* Settings updates
* Role creation and deletion
* API key changes

View the audit log at **Settings → Audit Log** or via the API:

```bash theme={null}
curl https://api.metrixllm.com/api/workspaces/{workspaceId}/audit?limit=50 \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Best practices

* **One workspace per environment** — Keep dev, staging, and production fully isolated.
* **Use least-privilege roles** — Give team members only the access they need. Use `viewer` for stakeholders who only need to read logs.
* **Set budget alerts early** — Configure spending alerts before going live to avoid surprises.
* **Enable IP allowlisting** in production to restrict which networks can call your gateway.
* **Review audit logs regularly** — Especially after team member changes or configuration updates.

## Common pitfalls

<Warning>
  **Cannot remove the owner.** If you need to transfer ownership, first promote another member to `owner`, then demote yourself.
</Warning>

* **Invite tokens expire after 7 days.** If a teammate doesn't accept in time, revoke the old invite and send a new one.
* **Admins cannot remove other admins.** Only owners can manage admin-level members.
* **Settings changes propagate via NATS.** There may be a brief delay (\< 1 second) before edge gateways pick up new configuration.
* **Free tier seat limit is 3.** If you need more members, upgrade to Pro or higher.