message.comDevelopers
Developers/Concepts/Workspace

What is a workspace?

A workspace is the top-level container in message.com. One business owns one workspace. Every conversation, agent, site, department, phone number, and integration is scoped to a single workspace. Cross-workspace data leakage is structurally impossible.

Definition

The workspace is the tenant boundary in a multi-tenant SaaS. It is the unit of billing, the unit of access control, and the unit of data isolation. The Postgres row-level security policies that run on every query check workspace_idagainst the JWT claims, so a stray query can never return another customer's data.

What a workspace owns

Almost everything in the platform sits inside a workspace:

  • Agents, their roles, and their channel assignments.
  • Departments and routing rules.
  • Sites where the widget is installed.
  • Phone numbers, voice profiles, and call recordings.
  • Inbound email addresses and outbound email domains.
  • Conversations, messages, notes, and uploads.
  • Knowledge base sources and vector embeddings.
  • Saved replies, saved views, and macros.
  • Billing subscription, plan, and AI engagement counters.

Workspace auth

Every API call carries a bearer token. The token encodes both the agent identity and the workspace ID. Sending a request to a different workspace's resource ID returns 404 not_found, identical to what you would see for a non-existent resource. The platform never confirms existence across tenants.

Read authentication for the JWT format and lifecycle. Workspace ID lives in the wid claim.

Sites under a workspace

A workspace can host many sites. A site is a single domain (or subdomain) where the widget is installed: acme.com, app.acme.com, blog.acme.com. Each site has its own widget config (color, position, custom greeting) while sharing the same agents, departments, and customer records at the workspace level.

Creating a workspace

Workspaces are created during signup at app.message.com/register. The first agent in the workspace is automatically an admin. Adding teammates is done from the Agents API or the dashboard.

Building multi-tenant integrations

If you are building an OAuth app on message.com (planned, see OAuth apps), your app handles many workspaces at once. Each customer installs your app into their workspace, granting it scoped permissions. Your code never crosses workspace boundaries: each access token is scoped to one tenant.