Skip to main content
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 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

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: 
tell setup-db init --workspace staging

​
Team members

​
Inviting users

Admins invite users by email with a specific role. Invitations expire after 7 days. 
curl -X POST https://your-tell-server/api/v1/admin/workspace/invites \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "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:
RolePurpose
ViewerView dashboards and analytics
EditorCreate and edit boards, saved metrics, and queries
AdminManage members, settings, and all content
PlatformCross-workspace operations (self-hosted deployments)
A user can have different roles in different workspaces. See Roles & Permissions for details.

​
Managing members

# 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 are workspace-scoped

​
Platform management

Users with the Platform role (typically your DevOps team) can manage workspaces across the entire deployment: 
# 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