Role-based access control (RBAC)
Use roles to control what users can do in the MotherDuck platform and which data they can read. A role combines platform permissions with data grants, so you can manage both dimensions in one place. Each role-management action, such as creating a custom role or assigning a role, requires its corresponding permission. The Admin preset role includes these permissions by default.
How roles work
A role carries two kinds of permission:
- Platform privileges: what a user can do in the MotherDuck platform, such as managing users, creating shares, or resetting a Duckling.
- Data grants: which Shares a user can read.
These two dimensions live on the same role but do not cascade into each other. Being a Builder does not grant READ on every Share in the organization. It means a Builder has READ access to the Shares that are granted to the Builder role.
Every user is provisioned with a preset role when their account is created. Creating custom roles requires permission to create custom roles, while assigning additional roles requires permission to assign roles. The Admin preset role includes both permissions by default.
Preset roles
MotherDuck provides three built-in roles that build on each other: each role includes everything the one below it can do. Admin includes everything Builder can do, and Builder includes everything Explorer can do.
| Role | Purpose | Cannot do |
|---|---|---|
| Admin | Govern the organization: billing, user and role management, SSO and SCIM configuration, service accounts, and all Builder capabilities. | Editing or deleting resources owned by another user, unless a capability explicitly permits it. |
| Builder | Produce data: query, create and manage databases and shares, manage Ducklings, manage service accounts, create Dives and notebooks, and create Flights. | Billing, user management, role management. |
| Explorer | Consume data: author and run SQL, attach shared databases, create databases and shares, and create and share owned Dives and Flights. | Billing, user management, service accounts, secret management, and compute audit. |
Preset roles are not configurable. Only their data grants change, through GRANT and REVOKE.
What each role can do
The following table summarizes platform capabilities for each preset role, where ✅ means the role has the capability and ❌ means it does not. Some rows group individual permissions that have the same preset-role mapping. Custom roles cannot select platform permissions individually. They receive platform capabilities from the preset and custom roles they inherit.
| Area | Capability | Admin | Builder | Explorer |
|---|---|---|---|---|
| Organization | Change organization display name | ✅ | ❌ | ❌ |
| Organization | Set the invite policy | ✅ | ❌ | ❌ |
| Organization | Configure SSO | ✅ | ❌ | ❌ |
| Organization | Configure SCIM | ✅ | ❌ | ❌ |
| Billing | View invoices | ✅ | ❌ | ❌ |
| Billing | Update payment method | ✅ | ❌ | ❌ |
| Billing | Select plan | ✅ | ❌ | ❌ |
| Users | View all users and roles | ✅ | ✅ | ✅ |
| Users | Invite users | ✅ | Depends on invite policy | Depends on invite policy |
| Users | Delete a user | ✅ | ❌ | ❌ |
| Users | Deprovision a user | ✅ | ❌ | ❌ |
| Users | Reactivate a user | ✅ | ❌ | ❌ |
| Users | Change a user's preset role | ✅ | ❌ | ❌ |
| Users | Create, configure, or drop a custom role | ✅ | ❌ | ❌ |
| Users | Assign or revoke additional roles | ✅ | ❌ | ❌ |
| Databases | View all organization databases | ✅ | ❌ | ❌ |
| Databases | View shared databases | ✅ | ✅ | ✅ |
| Databases | Create a database | ✅ | ✅ | ✅ |
| Databases | Drop an owned database | ✅ | ✅ | ✅ |
| Shares | Create shares | ✅ | ✅ | ✅ |
| Shares | Drop another user's shares | ❌ | ❌ | ❌ |
| Tokens | Create or revoke tokens | ✅ | ✅ | ✅ |
| Secrets | Create secrets | ✅ | ✅ | ❌ |
| Secrets | Delete secrets | ✅ | ✅ | ❌ |
| Compute | Change Duckling and read scaling size | ✅ | ✅ | ✅ |
| Compute | Change read scaling pool size | ✅ | ✅ | ✅ |
| Compute | Reset a Duckling | ✅ | ✅ | ✅ |
| SQL and Dives | Author and run SQL, create notebooks | ✅ | ✅ | ✅ |
| SQL and Dives | Create, edit, and delete owned Dives | ✅ | ✅ | ✅ |
| SQL and Dives | View and clone Dives | ✅ | ✅ | ✅ |
| Service accounts | Create, delete, or impersonate a service account | ✅ | ✅ | ❌ |
| Service accounts | Update service account Ducklings | ✅ | ✅ | ❌ |
| Flights | Create Flights | ✅ | ✅ | ✅ |
| Flights | Run or clone Flights | ✅ | ✅ | ✅ |
| Flights | View all organization Flights | ✅ | ❌ | ❌ |
| Flights | Edit or delete another user's Flights | ❌ | ❌ | ❌ |
| Guides | Create, edit, and delete owned Guides | ✅ | ✅ | ✅ |
| Guides | Read org-shared Guides | ✅ | ✅ | ✅ |
| Guides | Share a Guide with the whole organization | ✅ | ❌ | ❌ |
| Audit | View query history | ✅ | ✅ | ❌ |
| Audit | View Duckling overview | ✅ | ✅ | ❌ |
| Audit | View active accounts | ✅ | ✅ | ❌ |
Access checks evaluate the required platform permission, not a preset role name. Elsewhere in the documentation, prerequisites name the permission first and then list the preset roles that include it by default. A custom role satisfies the requirement when it inherits a role that includes the permission.
Custom roles
Custom roles are available on the Enterprise plan.
Create a custom role to give a team fine-grained Share access on top of inherited platform capabilities. You need permission to create custom roles, which the Admin preset role includes by default. You create a role with CREATE ROLE, then establish inheritance with GRANT ROLE. A custom role:
- Inherits all platform permissions from one or more preset or custom roles. You cannot add or remove individual platform permissions.
- Can receive Share grants directly, independently of the roles it inherits.
- Is additive on top of a user's preset role.
- Passes its grants down to any role that inherits it. When you grant READ on a Share to a custom role, every user who holds that role gets access, including users who hold other roles that inherit it.
You change what a role inherits at any time with GRANT ROLE and REVOKE ROLE, so a role is never permanently tied to a parent. MotherDuck rejects grants that would create a cycle or exceed the maximum hierarchy depth. To keep permission resolution predictable, keep custom role hierarchies shallow, ideally two to three levels.
Role names must be at least three characters, start with a letter, and contain only letters, numbers, hyphens, and underscores. Names are case-insensitive and stored in lowercase. admin, builder, and explorer are reserved and cannot be created or dropped.
For the commands, see CREATE ROLE and GRANT ROLE.
How data access grants flow
When you grant READ on a Share to a preset role, everyone at that trust level and above receives access. Because the preset roles are concentric, a grant to a lower role is inherited by every role above it. A grant to a custom role reaches everyone who holds that role, including users who hold any role that inherits it.
| Grant target | Who gets access |
|---|---|
GRANT READ ON SHARE ... TO ROLE explorer | Explorer, Builder, Admin, and any custom role that inherits from Explorer |
GRANT READ ON SHARE ... TO ROLE builder | Builder, Admin, and any custom role that inherits from Builder |
GRANT READ ON SHARE ... TO ROLE admin | Admin, and any custom role that inherits from Admin |
GRANT READ ON SHARE ... TO ROLE finance | Everyone who holds finance, plus any role that inherits finance |
A useful rule: grant to the lowest role that should have access, and every role that inherits it receives access automatically.
Users with multiple roles
A user can hold several roles at once. Their permissions resolve as the union of all assigned roles:
- Data access is the union of every grant across all of their roles.
- Platform permissions are the union of the effective permissions from every assigned role. A user with both Explorer and Builder gets Builder platform permissions because Builder includes Explorer. A custom role contributes the platform permissions of the roles it inherits.
Revoking a role removes only the access that role provided. A user who has data through another assigned role keeps it.
Users with no roles
A user becomes roleless if all their roles are revoked. A roleless user can sign in but sees an empty state and cannot access any data until someone with permission to assign roles assigns one. The Admin preset role includes this permission by default.
Public share links
Public share links ("anyone with the link") sit outside the role model. They grant access regardless of the role grants on that Share.
Migration from the earlier role model
Organizations created before role-based access control keep their access:
- Existing admins remain Admin, with no change.
- Existing members become Explorer, with no change to what they can do.