# Manage roles and access > Create custom roles, assign them to users, and grant Share access to roles in your MotherDuck organization. Roles let you manage what users can do and which data they can read. This guide covers the common admin tasks: creating custom roles, assigning roles to users, and granting data access. For the underlying model, see [Roles and access control](/docs/concepts/roles-and-access-control/). Role and grant management can be done through SQL or the UI. You can run the SQL statements from the MotherDuck SQL editor, a notebook, or any connected client. ## Prerequisites - **Creating, dropping, and assigning roles** requires the **Admin** role. - **Granting data access** on a Share requires that you own the Share. ## Understand the preset roles Every organization has three preset roles in a concentric hierarchy, where each role is a superset of the one below it. | Role | Use it for | | --- | --- | | **Admin** | Full organization control, including billing, members, and service accounts. | | **Builder** | Producing data: databases, shares, Ducklings, Dives, and Flights. Manage service accounts. | | **Explorer** | Consuming data: querying, attaching shares, and building owned Dives and Flights. | For the full capability breakdown, see [what each role can do](/docs/concepts/roles-and-access-control/#what-each-role-can-do). The **Roles** page under **Settings** → **Organization** → **Roles** shows the platform access each preset role adds, how many members hold it, and the custom roles in your organization. ![Roles settings page showing preset and custom roles](img/roles.png) ## Create a custom role :::note Custom roles are available on the Enterprise plan. ::: Create a custom role when a team needs scoped data access on top of a preset role. A custom role inherits its platform privileges from one parent role. ```sql -- Create the role, then set which role it inherits from. CREATE ROLE finance; GRANT ROLE explorer TO ROLE finance; ``` Members of `finance` now get Explorer platform privileges plus any grants made directly to `finance`. Use `CREATE ROLE IF NOT EXISTS finance;` to avoid an error if the role already exists. ## Assign roles to a user Assign one or more roles to a user. A user's effective permissions are the union of all their roles. ```sql GRANT ROLE finance TO USER alice; -- A user can hold several roles at once. GRANT ROLE builder TO USER alice; ``` With both `finance` and `builder`, Alice gets Builder platform privileges and the data grants from both roles. ## Grant data access to a role Grant READ on a Share to a role so that every current and future member of that role gets access without individual grants. The Share must be created with `ACCESS RESTRICTED`. ```sql -- Create a restricted share, then grant it to a role. CREATE OR REPLACE SHARE core_metrics FROM analytics (ACCESS RESTRICTED); GRANT READ ON SHARE core_metrics TO ROLE finance; ``` One statement can list several grantees of mixed type: ```sql GRANT READ ON SHARE core_metrics TO USER alice, USER jordan, ROLE finance; ``` To make a Share available to the whole organization, grant it to the Explorer role. Because roles are concentric, Builder and Admin inherit the grant: ```sql GRANT READ ON SHARE general_data TO ROLE explorer; ``` ## Remove a role or access Revoke a role from a user, or revoke a data grant from a role. ```sql -- Remove a role from a user. Their other roles are unaffected. REVOKE ROLE finance FROM USER alice; -- Remove data access from a role. REVOKE READ ON SHARE core_metrics FROM ROLE finance; ``` :::warning If you revoke a user's last role, they become roleless and lose access to all data until you assign a new role. MotherDuck warns you before completing this action. ::: To remove a custom role entirely, drop it. Users keep their other roles. ```sql DROP ROLE finance; ``` ## Audit roles and grants Use the `SHOW` commands to review who has which roles and what each role can access. ```sql -- List every role in the organization. SHOW ALL ROLES; -- List the members of a role. SHOW USERS OF ROLE finance; -- List the roles assigned to a user. SHOW ROLES TO USER alice; -- List who can read a Share. SHOW GRANTS ON SHARE core_metrics; ``` For output columns and permissions, see the [access control SQL reference](/docs/sql-reference/motherduck-sql-reference/access-control/). ## Move from ACCESS ORGANIZATION to role grants `ACCESS ORGANIZATION` on a Share is equivalent to granting READ to the Explorer role. Role grants are the preferred pattern and give you finer control over who has access. :::warning `ACCESS ORGANIZATION` is planned for deprecation after role-based access control is established. Grant org-wide access with `GRANT READ ON SHARE TO ROLE explorer` instead. ::: ## Related - [Roles and access control](/docs/concepts/roles-and-access-control/) - [Managing organizations](/docs/key-tasks/managing-organizations/) - [Access control SQL reference](/docs/sql-reference/motherduck-sql-reference/access-control/) - [Sharing data](/docs/key-tasks/sharing-data/sharing-overview/) --- ## Docs feedback MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`. For agents and automated tools, feedback submission should be user-confirmed before sending. URL-encode query parameter values and send a GET request: ```text GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fkey-tasks%2Fmanaging-organizations%2Fmanaging-roles%2F&page_title=Manage%20roles%20and%20access&text= ``` Optionally append `&source=` such as `claude.ai` or `chatgpt`. `page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": ""}`, `400` for malformed query parameters, and `429` when rate-limited.