Roles & scopes
The viewer · editor · builder · admin role model, and how API-key scopes narrow it.
Access has two layers: a member's role sets their maximum permissions, and an API key's scopes can narrow a key below that - never above.
The four roles
Each higher role includes everything below it.
| Role | Can do |
|---|---|
| Viewer | Query tables, export data, view schemas & metadata. |
| Editor | + Insert, update, delete rows. Import data. Connect storage. Run AI queries. |
| Builder | + Create, modify & delete tables, configure domains, delete objects, create/revoke API keys, manage AI credentials. |
| Admin | + Manage users & roles, organisation settings, SSO, and read the audit log. |
Every organisation also has an owner - ownership can't be accidentally transferred.
Assigning roles
Roles are set when a member is invited or updated, at the organisation level. New
SSO sign-ins get the connection's default_role (see
SSO with OIDC).
Workspace roles override per resource
A member of a non-default workspace also carries a
workspace role, and it - not the organisation role - governs that workspace's
shared storage and the tables under it. The override goes both directions: a
workspace role can grant more than the org role inside that workspace, or less.
An org Viewer given builder in a workspace can modify that workspace's tables;
an org Builder given viewer there cannot.
Personal storage and org-level surfaces (users, invites, SSO, workspace
management itself) always answer to the organisation role.
Effective permission is always governing role ∩ API-key scopes ∩ token scopes.
How key scopes narrow a role - and why they can never expand it - is covered in API keys.