Skip to content

Automatic translation — the Portuguese version is the reference. View in Portuguese

Organization and workspaces

On this page (10)

The Organization is an administrative layer above the workspace, for agencies, BPOs and multi-CNPJ (multi-company) groups that manage several clients/companies.

Concepts#

  • Organization: groups N workspaces. It is purely structural — it manages which workspaces exist and who administers them, without ever granting access to the data of any of them.
  • Workspace: the real unit of isolation (dedicated datalake, people, plan, billing). Data access always requires membership in the workspace.
  • Multi-CNPJ portfolio: within the model, you can organize multiple CNPJs (Brazilian company IDs), apps and audiences.

Availability#

  • Plans: all. The organization layer is core.
  • How it works: model covered by automated tests.

Permissions#

  • org_admin (organization role): administers the structure — creates/links workspaces, manages org members, adjusts org settings (org.* actions).
  • org_admin does NOT get automatic access to data in any workspace. To see data, they need to be a member/owner of that specific workspace.
  • The organization check is fail-closed: missing org context → denied; organization different from the target resource → denied (isolation between orgs).

Setup (step by step)#

  1. Create the organization (name; slug and owner optional).
  2. Link existing workspaces to the organization (it only associates them; it doesn't move data).
  3. Assign the org_admin role to whoever will administer the structure.
  4. To give access to a workspace's data, add the person as a member of that workspace (see Users and permissions).

Linking/unlinking a workspace is audited and never deletes the workspace or its data — unlinking only removes the link (organizationId = null).

Validation#

  • The org's administrative view lists all the org's workspaces.
  • The "only with access" view lists only the workspaces where the person is owner or an active/invited member — proving the anti-cross-access design.
  • Links appear in the audit log (organization.attach / organization.detach).

Example#

Grupo Aurora (organization) has two workspaces: Aurora Varejo and Aurora Atacado. João is org_admin: he creates and links workspaces and manages who administers them, but doesn't see the sales data of either one — for that, he would need to be a member of the workspace. Maria is a member only of Aurora Varejo: when listing the org, she gets only Aurora Varejo.

Cost#

  • Creating/managing the organization and links: R$ 0 (uses no processing).

Security#

  • Isolation between organizations and between workspaces is fail-closed.
  • The org is not a shortcut to data: strict separation between "administering the structure" and "accessing data".
  • Every structural change is audited and scoped to the affected workspace.

Limits#

  • The organization doesn't share datasets between workspaces.
  • Each workspace has its own datalake; one customer never reads another's data. The design is fail-closed.

Troubleshooting#

SymptomLikely causeWhat to do
org_admin can't see a workspace's dataexpected behavioradd the person as a member of the workspace
"Different organization — action denied"resource belongs to another orgwork within the correct org (isolation)
Workspace doesn't appear in the listperson has no membershipconfirm active membership in that workspace
"Organization context missing"org.* action with no org in contextaccess it through the correct org

Next steps: Users, groups and permissions.

Related links