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).
Roles vs key scopes
Good to know
So a builder can mint a key scoped to just tables:query for a read-only
dashboard, but a viewer cannot mint a key that inserts rows - the scope would
exceed their role and is rejected.
Scopes group into categories - Tables, Rows, Domains, Connections, Storage, AI,
API Keys, Organisation - with read / write / admin presets for common
patterns. See API keys.