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_admindoes 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)#
- Create the organization (name; slug and owner optional).
- Link existing workspaces to the organization (it only associates them; it doesn't move data).
- Assign the
org_adminrole to whoever will administer the structure. - 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#
| Symptom | Likely cause | What to do |
|---|---|---|
org_admin can't see a workspace's data | expected behavior | add the person as a member of the workspace |
| "Different organization — action denied" | resource belongs to another org | work within the correct org (isolation) |
| Workspace doesn't appear in the list | person has no membership | confirm active membership in that workspace |
| "Organization context missing" | org.* action with no org in context | access it through the correct org |
Next steps: Users, groups and permissions.