Workspaces

Documentation Index

Fetch the complete documentation index at: https://docs.chatblocks.ai/llms.txt

Use this file to discover all available pages before exploring further.

A workspace is the unit of billing, sharing, and access control in ChatBlocks. Every canvas, block, data source, BYOK API key, scheduled run, MCP API key, and audit log entry belongs to exactly one workspace.

​

Personal workspace on signup

When you finish /setup, a personal workspace is created for you automatically:

• Name: ${username}'s Workspace
• Slug: your username (collision-suffixed if taken)
• Plan: free
• You: the owner (immutable for billing) and an admin member.

You can create or join additional workspaces later; the cookie-based switcher (cb_current_workspace) decides which one is “active” in the web UI.

​

Roles

Workspace members carry one of two roles:

• admin — controls billing, members, connectors (data sources + BYOK keys), and API key minting. Admins are the “paid stuff” people.
• member — full creative powers: create / edit / delete blocks and canvases, configure scheduled runs, view the audit log.

The profiles.role flag (user vs admin) is a separate, site-wide concept — used for site admin actions like setting the featured homepage canvas. A site admin and a workspace admin are independent: you can be a site admin who’s just a member on someone else’s workspace, or a workspace admin who’s a regular user site-wide.

​

Permissions reference

​

Builder co-member model

Builder is a single-operator paid plan. The owner (the paying account) gets agent-write powers: their actions — and any actions taken by an MCP key minted on their workspace — can create, edit, publish, delete blocks; create canvases; configure schedules. Co-members on a Builder workspace are read-only viewers. They can open the workspace, see canvases, view the audit log — but createBlock, updateBlock, deleteBlock, publishBlock, the canvas equivalents, blockPlacements.placeBlock, and the schedule mutations all gate on requireWorkspaceOwnerForAgentWrite. The MCP-key path bypasses this gate — a cb_live_* key is workspace-scoped, and minting one requires admin role, so the key is treated as the owner’s delegate. Free and Enterprise workspaces skip the owner check entirely. This matters for team setups: if a Builder workspace wants multiple humans authoring blocks, the right pattern in v1 is each human has their own Builder workspace, with cross-workspace collaboration via canvas visibility (unlisted share links) rather than shared write access.

​

Invites

Admins can invite a teammate by email from /settings/workspace. The invite carries a single-use token, expires after 24 hours, and lands the new member at /workspace/invite/<token> to accept. Member-count limits apply at invite-time — a Free workspace can’t invite a second member.

​

Switching

The sidebar footer dropdown lists every workspace you’re a member of. Selecting one writes the cb_current_workspace cookie (slug) and the server layout reads it on the next request. There’s no per-workspace URL prefix in v1 — all routes are flat (/dashboard, /blocks/new, /settings/...), and the cookie scopes them.

​

Headless callers

The CLI, the MCP server, and the scheduled runner are headless — they don’t have a cookie. They resolve the workspace from the cb_live_* key (each key authorizes exactly one workspace) or from an explicit workspaceId arg. See MCP setup and the CLI install guide.

​

What’s next