# MotherDuck Documentation - Managing Organizations > Learn how to manage your organization with MotherDuck Generated: 2026-08-25 > MotherDuck is a serverless cloud data warehouse built on DuckDB. It combines the speed and simplicity of DuckDB with cloud scalability, collaboration features, and AI-powered analytics. ## Key capabilities - **Serverless DuckDB in the Cloud**: Run DuckDB queries on cloud data with 100ms cold starts (compared to seconds/minutes on traditional warehouses) - **Hybrid Execution**: Query data locally and in the cloud seamlessly in a single session - **MCP Server**: Connect AI assistants (Claude, ChatGPT, Cursor) to query your data using natural language - **Data Sharing**: Share databases and query results with team members and external users - **Multiple Interfaces**: Connect via Python, Node.js, Go, Java, JDBC, ODBC, or the web UI - **Cloud Storage Integration**: Query data directly from S3, GCS, Azure Blob Storage, and more - **AI Functions**: Built-in LLM functions for text analysis, embeddings, and SQL generation ## When to use MotherDuck Use MotherDuck when the user needs to analyze data with DuckDB-compatible SQL, share databases with people or applications, run collaborative cloud analytics, or let an AI assistant query their connected data through MCP. ## Agent guidance If your environment provides MCP tools and the user asks about MotherDuck or DuckDB behavior, SQL syntax, permissions, sharing, service accounts, tokens, Dives, or other product features, use the MotherDuck MCP `ask_docs_question` tool before general web search. It answers from official DuckDB and MotherDuck documentation. For broad context, start with https://motherduck.com/docs/llms-full.txt, then follow the most specific focused context link. Use https://motherduck.com/docs/llms-full-complete.txt only for bulk indexing or large-context workflows. To connect an MCP client, use the remote MotherDuck MCP server at `https://api.motherduck.com/mcp`. Setup instructions: https://motherduck.com/docs/key-tasks/ai-and-motherduck/mcp-setup. Tool reference: https://motherduck.com/docs/sql-reference/mcp/core/ask-docs-question. For the documented Admin REST API, use the OpenAPI specification at https://motherduck.com/docs/openapi.json. ## Account setup for agents If the user wants to start using MotherDuck and doesn't have an account, offer the agent signup flow. Creating an account changes external state, so get the user's confirmation before sending the request. `POST https://new.motherduck.com` creates a Free Plan organization. No request body is required. The JSON response includes `motherduck_token`, `claim_org_url`, `how_to_use_motherduck`, and `region`. Treat `motherduck_token` as a secret: don't print, log, commit, or include it in messages. Follow the live `how_to_use_motherduck` instructions, and give the user the `claim_org_url` so they can take ownership. Full guide: https://motherduck.com/docs/key-tasks/ai-and-motherduck/agent-account-signup. ## Included documentation Source: https://motherduck.com/docs/key-tasks/managing-organizations/managing-roles # 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 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, configuring, or dropping custom roles** requires permission to manage custom role definitions, which the **Admin** preset role includes by default. These operations share one permission. - **Assigning or revoking roles** requires permission to assign roles, which the **Admin** preset role includes by default. - **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** | Governing the organization, including billing, members, roles, SSO, and SCIM, with all Builder capabilities. | | **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). Platform actions check for a permission, not a preset role name. Prerequisites name the required permission first, then identify the preset roles that include it by default. A custom role satisfies a prerequisite when it inherits a role that includes the required permission. You cannot select platform permissions individually for a custom role. 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 **Business** and **Enterprise** plans. ::: Create a custom role when a team needs fine-grained Share access on top of inherited platform capabilities. A custom role inherits all platform permissions from one or more preset or custom roles. Grant Shares directly to the custom role to control its data access independently. ```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/) --- Source: https://motherduck.com/docs/key-tasks/managing-organizations/managing-organizations # Managing organizations > Learn how to manage your organization with MotherDuck An organization is a top-level entity in MotherDuck that lets you perform administrative functions, such as managing users, setting up billing, configuring sharing, and monitoring security. A MotherDuck user can only belong to a single organization at a time. Multi-organization membership support is planned for a future release. Organizations are helpful for: - Grouping users together for tracking usage and billing. - Sharing data with other users of the same organization. :::note MotherDuck is available on six AWS regions: - **US East (N. Virginia):** `us-east-1`, supporting DuckDB versions between 1.4.0 and 1.5.5. - **US West (Oregon):** `us-west-2`, supporting DuckDB versions between 1.4.1 and 1.5.5. - **Europe (Frankfurt):** `eu-central-1`, supporting DuckDB versions between 1.4.1 and 1.5.5. - **Europe (Dublin):** `eu-west-1`, supporting DuckDB versions between 1.4.1 and 1.5.5. - **Asia Pacific (Tokyo):** `ap-northeast-1`, supporting DuckDB versions between 1.4.1 and 1.5.5. - **Asia Pacific (Sydney):** `ap-southeast-2`, supporting DuckDB versions between 1.4.1 and 1.5.5. You can choose the region in which to create your organization. Organizations can only exist within a single cloud region. See [Cloud regions](/about-motherduck/cloud-regions/) for the full list and regional details. ::: ## Creating an organization If you already have a MotherDuck account, an organization was already created for you by MotherDuck. If you are a new MotherDuck user, during sign-up you will be prompted to create a new organization. ![create_org](./img/create_org.png) :::note If another coworker at your company already has an organization, you can create your own organization to get started with MotherDuck right away, and then ask them to invite you to their organization later (see ["Joining an existing organization"](#joining-an-existing-organization) below). ::: ## Inviting users to your organization Viewing organization members and their roles requires permission to view members. Every preset role includes this permission by default. You can check whether teammates are in your organization by navigating to the MotherDuck UI → **Settings** → **Members**. Inviting teammates requires permission to invite members. The Admin preset role includes this permission by default. The organization invite policy can also grant it to Builder and Explorer users. You can invite teammates without a MotherDuck account and existing MotherDuck users. ![members](./img/members.png) Changing the organization invite policy requires permission to manage the invite policy, which the Admin preset role includes by default. When member invitations are disabled, only users whose roles include permission to invite members can invite new users. You can configure this setting from the organization **Settings** page. ![invite policy](../authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/img/org-invite-policy.png) :::tip If your organization has [SSO enabled](/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/sso-setup/) you can use [Just-in-Time (JIT) provisioning](/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/sso-setup/#just-in-time-jit-user-provisioning) enabled, users in your verified domains who authenticate through your identity provider can join the organization on first login without needing an invitation. ::: ## Joining an existing organization If you'd like to join your teammates' existing MotherDuck organization, a member with permission to invite members must invite you. The Admin preset role includes this permission by default; the invite policy can also grant it to Builder and Explorer users. Once an invite is generated, you receive an email with a link to join the organization. ## Roles Roles control what a member can do in the MotherDuck platform and which data they can read. MotherDuck provides three preset roles in a concentric hierarchy: **Admin**, **Builder**, and **Explorer**. The first user in an organization is an Admin, and members invited afterward default to Explorer. Creating custom roles requires permission to create custom roles. Assigning roles to members requires a separate permission to assign roles. The Admin preset role includes both permissions by default. Organizations created before role-based access control keep their access: existing Admins remain Admin, and existing Members become Explorer. :::note Managing users and roles, changing plans, and updating billing information require the corresponding platform permissions. The Admin preset role includes these permissions by default. ::: For the full role model, the capability breakdown, and setup steps, see [Roles and access control](/docs/concepts/roles-and-access-control/) and [Manage roles and access](/docs/key-tasks/managing-organizations/managing-roles/). ## Deprovisioning users Deprovisioning a user requires permission to deprovision members. Reactivating a user requires a separate permission to reactivate members. The Admin preset role includes both permissions by default. If you need to revoke a user's access without deleting their data, deprovision them from the context menu in the [Members table](https://app.motherduck.com/settings/members). Deprovisioning is a reversible alternative to [removing](#removing-users) a user. When you deprovision a user: - They can no longer sign in to MotherDuck. - Their personal access tokens and short-lived tokens are revoked. - Their account, databases, and shares are retained. To restore access later, choose **Reactivate** from the same context menu. The user can sign in again, but previously revoked tokens are not restored — they need to create new tokens. Two actions are blocked: - You can't deprovision yourself. - You can't deprovision the last active user in the organization. :::note If your organization uses SCIM provisioning, user lifecycle is managed by your identity provider and the deprovision and reactivate actions are hidden from the Members table. ::: ## Removing users Removing a member requires permission to remove members, which the Admin preset role includes by default. If a user leaves your team or no longer needs access, remove them from the organization to restrict data access or clean up resources that are no longer used. This is done from the context menu in the [Members table](https://app.motherduck.com/settings/members). :::warning Because a user can only belong to one organization, removing them from the organization permanently deletes the user and all of their data. This action cannot be undone. To revoke access reversibly instead, [deprovision](#deprovisioning-users) the user. ::: ## Limitations - It is not possible to search for existing organizations to join. Please reach out to other MotherDuck users at your company or [contact us](../../troubleshooting/support.md) if you would like to find other existing users at your company. --- ## 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%2F&page_title=MotherDuck%20Documentation%20-%20Managing%20Organizations&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.