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

# Workspaces & Teams

> Multi-tenant workspaces with team member management and data isolation.

Every Tell deployment is organized into workspaces. Each workspace is a fully isolated environment — its own database, API keys, team members, and analytics data. Nothing leaks between workspaces.

## How workspaces work

When you run Tell for the first time, [setup](/api/authentication) creates your first workspace and admin account. From there, you can create additional workspaces for each app, product, or environment you want to track separately.

The most common pattern is **one workspace per app** — like projects on Vercel. If you ship a web app, a mobile app, and an internal tool, each gets its own workspace with its own data, API keys, and team access.

* **my-saas-app** — product analytics and logs for your main product
* **mobile-app** — iOS and Android event tracking
* **marketing-site** — page views and conversion tracking
* **internal-tools** — operational dashboards

You can also use workspaces to separate environments (production vs staging) or departments — whatever boundary makes sense for your setup.

Each workspace gets its own ClickHouse database and its own set of streaming API keys.

## Creating a workspace

```bash theme={null}
curl -X POST https://your-tell-server/api/v1/user/workspaces \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Staging", "slug": "staging"}'
```

The slug is a URL-friendly identifier (alphanumeric and hyphens, 1-50 characters). You automatically become the admin of any workspace you create.

After creating a workspace, run `tell setup-db init` to create its ClickHouse database and tables:

```bash theme={null}
tell setup-db init --workspace staging
```

## Team members

### Inviting users

Admins invite users by email with a specific role. Invitations expire after 7 days.

```bash theme={null}
curl -X POST https://your-tell-server/api/v1/admin/workspace/invites \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "analyst@example.com", "workspace_id": "ws_abc123", "role": "editor"}'
```

The invited user receives a link to accept the invitation. If they don't have a Tell account yet, one is created when they accept.

### Roles

Each team member has a role that controls what they can do:

| Role         | Purpose                                              |
| ------------ | ---------------------------------------------------- |
| **Viewer**   | View dashboards and analytics                        |
| **Editor**   | Create and edit boards, saved metrics, and queries   |
| **Admin**    | Manage members, settings, and all content            |
| **Platform** | Cross-workspace operations (self-hosted deployments) |

A user can have different roles in different workspaces. See [Roles & Permissions](/running-tell/roles) for details.

### Managing members

```bash theme={null}
# List workspace users
curl "https://your-tell-server/api/v1/admin/users?limit=50" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

# Change a user's role
curl -X PUT https://your-tell-server/api/v1/admin/users/{user-id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}'

# Remove a user
curl -X DELETE https://your-tell-server/api/v1/admin/users/{user-id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"
```

You can't assign a role higher than your own — an Admin can't make someone a Platform user.

## Workspace isolation

Workspaces are isolated at every level:

* **Database** — each workspace gets a separate ClickHouse database
* **API keys** — streaming keys and programmatic keys are scoped to a workspace
* **Queries** — SQL queries are automatically scoped to the workspace's database
* **Boards and metrics** — all content belongs to a workspace
* **Audit logs** — [audit events](/running-tell/audit-privacy) are workspace-scoped

## Platform management

Users with the Platform role (typically your DevOps team) can manage workspaces across the entire deployment:

```bash theme={null}
# List all workspaces
curl https://your-tell-server/api/v1/admin/workspaces \
  -H "Authorization: Bearer $TOKEN"

# Delete a workspace
curl -X DELETE https://your-tell-server/api/v1/admin/workspaces/{id} \
  -H "Authorization: Bearer $TOKEN"
```

Deleting a workspace permanently removes all its data, members, and API keys.

## What's next

* [Roles & Permissions](/running-tell/roles) — detailed role and permission reference
* [API Keys](/running-tell/api-keys) — managing streaming and programmatic keys
* [Workspaces API](/api/workspaces) — full HTTP API reference