Role-based access control (RBAC) defines what each person can do. There are 4 workspace roles (with cumulative inheritance) plus 1 organization role, which is orthogonal.
The 5 roles#
Workspace (cumulative inheritance owner ⊇ admin ⊇ member ⊇ viewer):
| Role | Profile | Summary |
|---|---|---|
viewer | Consumes | sees dashboards and reports |
member | Basic analyst | everything viewer has + interacts (filters/drill) and exports |
admin | Operator | everything member has + runs queries/refresh/AI, manages content, sources, people and keys |
owner | Owner | everything admin has + billing, workspace deletion and role assignment |
Organization (separate dimension):
| Role | Profile | Summary |
|---|---|---|
org_admin | Administers the structure | manages the org's workspaces/members/settings — no access to data |
owneris structural (the workspace owner). A regular member never becomesownerthrough configuration — the boundary is fail-closed.
Role × capability matrix#
| Action (RBAC) | viewer | member | admin | owner | org_admin |
|---|---|---|---|---|---|
| dashboard viewing / report viewing | ✓ | ✓ | ✓ | ✓ | — |
| data interaction (filters/drill) | — | ✓ | ✓ | ✓ | — |
| data export | — | ✓ | ✓ | ✓ | — |
data.query.run | — | — | ✓ | ✓ | — |
refresh.trigger | — | — | ✓ | ✓ | — |
| AI features | — | — | ✓ | ✓ | — |
| dashboard management / report management | — | — | ✓ | ✓ | — |
source.manage | — | — | ✓ | ✓ | — |
member.manage | — | — | ✓ | ✓ | — |
apikey.manage | — | — | ✓ | ✓ | — |
workspace.settings | — | — | ✓ | ✓ | — |
billing.manage | — | — | — | ✓ | — |
workspace.delete | — | — | — | ✓ | — |
role.assign | — | — | — | ✓ | — |
org.workspace.manage | — | — | — | — | ✓ |
org.member.manage | — | — | — | — | ✓ |
org.settings | — | — | — | — | ✓ |
Availability#
- Plans: all. RBAC is a core security feature.
- How it works: deterministic matrix, covered by automated tests.
Permissions#
- Only the owner can assign roles (
role.assign). - admin can manage people (
member.manage), but not billing or deleting the workspace.
Setup#
- The member's role comes from
permissionsJson.role(admin/member/viewer). - Missing/invalid role →
member(legacy default); unknown value or an attempt atownervia JSON →viewer(fail-closed). - The
org_adminrole is assigned in the organization context.
Validation (fail-closed)#
- Unknown/garbage role → treated as
viewer(least privilege). - Unknown action → denied (it doesn't belong to any set).
org_adminonly enablesorg.*actions — never workspace data.
Example#
At Comércio Aurora: Maria is owner (does everything, including billing). João is
admin (runs pipelines, manages sources and people, but doesn't handle billing). Ana is member
(interacts and exports). Managers are viewer. In Grupo Aurora, João is also
org_admin to administer the organization's structure — without seeing the sales
data because of it.
Cost#
- RBAC uses no cloud resources: R$ 0.
Security#
- Fail-closed at every boundary; least privilege as the default.
- RBAC is a check made before the account-in-good-standing check: a role without the capability → 403 without even querying the central billing service.
org_adminisolated from data (the org is structural).
Limits#
- 5 fixed roles (4 workspace + 1 org). Fully custom roles are not part of the current product.
- For row-level restriction (e.g., only your own branch), RBAC isn't enough — use RLS/ABAC.
Troubleshooting#
| Symptom | Likely cause | What to do |
|---|---|---|
| Member can't handle billing | only owner has billing.manage | action exclusive to the owner |
| "Action not allowed for the role" | role below what's required | raise the role (owner assigns) |
org_admin can't see data | expected behavior | become a member of the target workspace |
| Role "dropped" to viewer | invalid JSON / attempt at owner | correct the role to admin/member/viewer |
Next steps: Row-level security (RLS).