Concepts
What X-Workspace-Id gates, how organization roles work, and how regions pin your data.
Workspaces & scoping
Every resource on the platform — signals, segments, models, pipelines,
trainings, deployments, goals — belongs to exactly one workspace, and data
never crosses workspace boundaries. The X-Workspace-Id header selects
which workspace a request operates on; a workspace you can't access gets
you a 401 or 403, never someone else's data.
Three things grant access to a workspace:
| Access via | Who |
|---|---|
| Ownership | The user who created it (owner) |
| Organization membership | Any member of the organization that owns it |
| Explicit member grant | A user added through workspace members |
The routes in this section are the exception to the header rule: they
authenticate with Authorization alone, because you use them to discover
and manage workspaces before you have an ID to send. (On
create workspace,
X-Workspace-Id is optional — if you send it and it names an
organization workspace, the new workspace is attached to the same
organization.)
Organizations & roles
An organization groups people and workspaces: shared membership, shared billing, and role-based permissions. Each member holds one of four roles:
| Role | Can do |
|---|---|
admin | Everything — organization settings, members and invitations, billing, and all workspace resources. |
billing | View and manage billing. |
member | Create and manage resources: workspaces, segments, models, deployments. |
viewer | Read-only. |
The organization's owner (its creator) implicitly holds every
permission, like an admin. Roles are assigned when a member is
invited and changed with the
role endpoint.
Organization roles are separate from workspace member roles
(viewer / editor / admin), which grant access to a single
workspace only. See Workspace members.
Regions
Each workspace is pinned to a region at creation — the region where
its data physically lives — and it never moves afterwards. Your API base
URL follows the region: requests that land in the wrong one get a 409
redirect with the correct base URL (see
Authentication → Regions).
When you create a workspace, the region resolves in this order:
- An explicit
regionin the request body — must be one of the available regions. - Your account's (or organization's) home region.
- A default derived from your stored country.
Most callers never set it: the default keeps a workspace co-located with the account that owns it.