# MotherDuck Documentation - Service accounts > Learn how to create, configure, manage, and impersonate MotherDuck service accounts. 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/service-accounts-guide/create-and-configure-service-accounts # Create and configure service accounts > Learn how to create service accounts, create access tokens, and configure Duckling resources. A service account is a non-human user identity for workloads that need to connect to MotherDuck without using a person's credentials. Use service accounts for backend services, scheduled pipelines, BI connections, embedded analytics, and customer-facing analytics workloads. Each service account has its own credentials and Duckling configuration. This gives the workload isolated compute and makes it easier to rotate credentials without disrupting human users. :::warning[Service account permissions required] Creating service accounts, creating service account tokens, and configuring service account Ducklings in the MotherDuck UI each require the corresponding permission. The Admin and Builder preset roles include these permissions by default. The Admin REST API still requires a read/write access token generated by an Admin user. Pass the token in the `Authorization` header as `Bearer `. ::: ## Create a service account Choose a stable username for the service account. The username must be unique within your organization and can contain letters, numbers, and underscores. ### UI ![Service account creation form](../img/sa_ui.png) 1. In the MotherDuck UI, go to **Settings** > **Service Accounts**. 2. Click **Create service account**. 3. Enter a username for the service account. 4. Click **Create service account**. ### API using curl Use the [`POST /v1/users`](/sql-reference/rest-api/users-create-service-account/) endpoint to create a service account. ```bash curl -X POST \ https://api.motherduck.com/v1/users \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "username": "analytics_service_account" }' ``` The response includes the service account `username`. Store this username in your provisioning system. The REST API doesn't provide an endpoint for listing all service accounts in an organization. ### API using Python Use the [`POST /v1/users`](/sql-reference/rest-api/users-create-service-account/) endpoint to create a service account. ```python import requests response = requests.post( "https://api.motherduck.com/v1/users", headers={ "Authorization": "Bearer ", "Content-Type": "application/json", }, json={"username": "analytics_service_account"}, ) response.raise_for_status() print(response.json()["username"]) ``` The response includes the service account `username`. Store this username in your provisioning system. The REST API doesn't provide an endpoint for listing all service accounts in an organization. ## Create an access token Create a token for the service account after you create the account. The token value is shown only once, so store it in a secret manager before closing the modal or discarding the API response. ### UI ![Service account details page](../img/sa_details.png) 1. In **Settings** > **Service Accounts**, open the service account details page. 2. Click **Create token**. 3. Enter a token name. 4. Choose the token type: - **Read/Write Token** for writes, administration, and general service workloads. - **Read Scaling Token** for read-heavy workloads that should use [read scaling](/key-tasks/authenticating-and-connecting-to-motherduck/read-scaling/). 5. To set an expiration, select **Automatically expire this token** and choose a time-to-live. 6. Click **Create token**, then copy the token and store it securely. ### API using curl Use the [`POST /v1/users/{username}/tokens`](/sql-reference/rest-api/users-create-token/) endpoint to create a token for a known service account username. ```bash curl -X POST \ https://api.motherduck.com/v1/users/analytics_service_account/tokens \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "name": "analytics-service-token", "token_type": "read_write" }' ``` Set `token_type` to `read_scaling` when you need a [read scaling token](/key-tasks/authenticating-and-connecting-to-motherduck/read-scaling/). To create an expiring token, include `ttl` as seconds between `300` and `31536000`. ### API using Python Use the [`POST /v1/users/{username}/tokens`](/sql-reference/rest-api/users-create-token/) endpoint to create a token for a known service account username. ```python import requests response = requests.post( "https://api.motherduck.com/v1/users/analytics_service_account/tokens", headers={ "Authorization": "Bearer ", "Content-Type": "application/json", }, json={ "name": "analytics-service-token", "token_type": "read_write", }, ) response.raise_for_status() token = response.json()["token"] print(token) ``` Set `token_type` to `read_scaling` when you need a [read scaling token](/key-tasks/authenticating-and-connecting-to-motherduck/read-scaling/). To create an expiring token, include `ttl` as seconds between `300` and `31536000`. :::note If you create a service account through the API and plan to use read scaling, connect as that service account with a read/write token before using read scaling tokens for that account. ::: ## Configure Ducklings Configure Duckling resources for the service account based on the workload it runs. The read/write Duckling handles writes and general queries. The read scaling pool handles read-only connections that use read scaling tokens. ### UI ![Service account Duckling size settings](../img/sa_set_instance_size.png) 1. In **Settings** > **Service Accounts**, find the service account. 2. Use the **Read/Write Duckling** dropdown to choose the read/write Duckling size. 3. If you use [read scaling](/key-tasks/authenticating-and-connecting-to-motherduck/read-scaling/), choose the read scaling Duckling size and pool size. ### API using curl Use [`GET /v1/users/{username}/instances`](/sql-reference/rest-api/ducklings-get-duckling-config-for-user/) to inspect the current configuration before updating it. ```bash curl -X GET \ https://api.motherduck.com/v1/users/analytics_service_account/instances \ -H "Authorization: Bearer " ``` Then use [`PUT /v1/users/{username}/instances`](/sql-reference/rest-api/ducklings-set-duckling-config-for-user/) to update the service account's Ducklings. ```bash curl -X PUT \ https://api.motherduck.com/v1/users/analytics_service_account/instances \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "config": { "read_write": { "instance_size": "standard" }, "read_scaling": { "instance_size": "pulse", "flock_size": 4 } } }' ``` The update request requires both `read_write` and `read_scaling` configuration blocks. ### API using Python Use [`GET /v1/users/{username}/instances`](/sql-reference/rest-api/ducklings-get-duckling-config-for-user/) to inspect the current configuration before updating it. ```python import requests headers = {"Authorization": "Bearer "} current_config = requests.get( "https://api.motherduck.com/v1/users/analytics_service_account/instances", headers=headers, ) current_config.raise_for_status() print(current_config.json()) ``` Then use [`PUT /v1/users/{username}/instances`](/sql-reference/rest-api/ducklings-set-duckling-config-for-user/) to update the service account's Ducklings. ```python import requests response = requests.put( "https://api.motherduck.com/v1/users/analytics_service_account/instances", headers={ "Authorization": "Bearer ", "Content-Type": "application/json", }, json={ "config": { "read_write": {"instance_size": "standard"}, "read_scaling": { "instance_size": "pulse", "flock_size": 4, }, } }, ) response.raise_for_status() print(response.json()) ``` The update request requires both `read_write` and `read_scaling` configuration blocks. ## Connect as the service account Use the service account token anywhere you would use a MotherDuck access token. For example, set `motherduck_token` in a DuckDB connection string or set `MOTHERDUCK_TOKEN` in your environment. See [Connecting to MotherDuck](/key-tasks/authenticating-and-connecting-to-motherduck/connecting-to-motherduck/) for connection string examples. ## Related content - [Manage service accounts and tokens](/key-tasks/service-accounts-guide/manage-service-accounts-and-tokens/) - [Impersonate service accounts](/key-tasks/service-accounts-guide/impersonate-service-accounts/) - [MotherDuck REST API](/sql-reference/rest-api/motherduck-rest-api/) - [Read scaling](/key-tasks/authenticating-and-connecting-to-motherduck/read-scaling/) --- Source: https://motherduck.com/docs/key-tasks/service-accounts-guide/impersonate-service-accounts # Impersonate service accounts > Use UI impersonation to troubleshoot and inspect resources as a service account. Impersonating a service account in the MotherDuck UI requires permission to impersonate service accounts. The Admin and Builder preset roles include this permission by default. Impersonation is useful when you need to inspect resources, run one-off queries, or troubleshoot service account-specific behavior from that account's point of view. Impersonation is different from using a service account token. Tokens are for applications and automation. Impersonation is an interactive UI workflow for users with the required permission. :::warning[UI only] Service account impersonation is available only in the MotherDuck UI. DuckDB clients, the CLI, and the REST API don't support impersonation sessions. Use service account tokens for non-UI access. ::: ## Start an impersonation session ![Service account impersonation action](../img/sa_impersonate_option.png) 1. In the MotherDuck UI, go to **Settings** > **Service Accounts**. 2. Open the three-dot menu for the service account. 3. Click **Impersonate this account**. 4. The UI refreshes and signs you in as the service account. While impersonating, MotherDuck shows a banner with controls to refresh the session or return to your original account. ![Service account impersonation banner](../img/sa_impersonate_banner.png) Impersonation sessions expire after two hours. Refresh the browser tab to reset the expiry countdown. :::tip You can bookmark the URL while impersonating a service account. Opening the bookmark starts a new impersonation session for the same service account when you're signed in with permission to impersonate service accounts. ::: ## Use impersonation for troubleshooting Use impersonation when you need to: - Verify which databases, shares, secrets, and Dives the service account can access. - Run read-write actions as the service account from the MotherDuck UI. - Inspect query history and ongoing query activity for that service account. - Confirm that a service account-specific setup works before wiring it into an application. ## Use tokens for applications Applications and DuckDB clients should connect with a service account token instead of impersonation. Create a read/write token for workloads that need to write data or manage resources. Create a read scaling token for read-heavy workloads that should use [read scaling](/key-tasks/authenticating-and-connecting-to-motherduck/read-scaling/). ## Related content - [Create and configure service accounts](/key-tasks/service-accounts-guide/create-and-configure-service-accounts/) - [Manage service accounts and tokens](/key-tasks/service-accounts-guide/manage-service-accounts-and-tokens/) - [Connecting to MotherDuck](/key-tasks/authenticating-and-connecting-to-motherduck/connecting-to-motherduck/) --- Source: https://motherduck.com/docs/key-tasks/service-accounts-guide/manage-service-accounts-and-tokens # Manage service accounts and tokens > Use the MotherDuck UI and REST API to view, delete, and rotate service account tokens. Use the MotherDuck UI for service account inventory and one-off administration. Use the REST API when your automation already knows the target service account username. :::warning[Service account permissions required] Viewing or managing service accounts and their tokens in the MotherDuck UI requires the corresponding permission for each action. The Admin and Builder preset roles include these permissions by default. The Admin REST API examples require a read/write access token generated by an Admin user. ::: ## Check what each interface supports | Task | MotherDuck UI | REST API | |---|---|---| | List all service accounts in an organization | Yes | No | | Create a service account | Yes | Yes, with [`POST /v1/users`](/sql-reference/rest-api/users-create-service-account/) | | View tokens for a known service account | Yes | Yes, with [`GET /v1/users/{username}/tokens`](/sql-reference/rest-api/users-list-tokens/) | | Create a token for a known service account | Yes | Yes, with [`POST /v1/users/{username}/tokens`](/sql-reference/rest-api/users-create-token/) | | Revoke a known token | Yes | Yes, with [`DELETE /v1/users/{username}/tokens/{token_id}`](/sql-reference/rest-api/users-delete-token/) | | Delete a known service account | Yes | Yes, with [`DELETE /v1/users/{username}`](/sql-reference/rest-api/users-delete/) | | View or configure Ducklings for a known service account | Yes | Yes, with the [Duckling configuration endpoints](/sql-reference/rest-api/ducklings-get-duckling-config-for-user/) | | Impersonate a service account | Yes | No | The REST API doesn't provide an endpoint for listing all service accounts in an organization. If you provision service accounts through the API, store the returned usernames in your own system. ## View service accounts ### UI ![Service account management page](../img/sa_manage_details.png) 1. In the MotherDuck UI, go to **Settings** > **Service Accounts**. 2. Review the service account list. 3. Click a username to view that service account's details and tokens. 4. Use the Duckling size and pool size dropdowns to review compute configuration. ### API The REST API doesn't provide a service account list endpoint. Use the UI to view organization-level service account inventory. For automated provisioning, persist the `username` returned by [`POST /v1/users`](/sql-reference/rest-api/users-create-service-account/) when you create each service account. ## View tokens for a service account The token list shows token metadata, including token ID, name, type, creation time, and expiration time. It doesn't return the token secret. ### UI 1. In **Settings** > **Service Accounts**, open the service account details page. 2. Review the token list. ### API using curl Use [`GET /v1/users/{username}/tokens`](/sql-reference/rest-api/users-list-tokens/) to list tokens for a known service account username. ```bash curl -X GET \ https://api.motherduck.com/v1/users/analytics_service_account/tokens \ -H "Authorization: Bearer " ``` ### API using Python Use [`GET /v1/users/{username}/tokens`](/sql-reference/rest-api/users-list-tokens/) to list tokens for a known service account username. ```python import pprint import requests response = requests.get( "https://api.motherduck.com/v1/users/analytics_service_account/tokens", headers={"Authorization": "Bearer "}, ) response.raise_for_status() pprint.pp(response.json()["tokens"]) ``` ## Rotate a service account token Rotate tokens by creating a replacement token before revoking the old token. 1. Create a replacement token for the service account. 2. Update your secret manager or application configuration to use the replacement token. 3. Deploy or restart clients that use the token. 4. Verify that the workload can connect to MotherDuck with the replacement token. 5. Revoke the old token. ## Revoke a token ### UI ![Service account token actions](../img/sa_revoke_token_option.png) 1. In **Settings** > **Service Accounts**, open the service account details page. 2. Open the token's three-dot menu. 3. Click **Revoke token**. 4. Confirm the revocation. ### API using curl Use [`DELETE /v1/users/{username}/tokens/{token_id}`](/sql-reference/rest-api/users-delete-token/) to revoke a known token. ```bash curl -X DELETE \ "https://api.motherduck.com/v1/users/analytics_service_account/tokens/" \ -H "Authorization: Bearer " ``` ### API using Python Use [`DELETE /v1/users/{username}/tokens/{token_id}`](/sql-reference/rest-api/users-delete-token/) to revoke a known token. ```python import requests response = requests.delete( "https://api.motherduck.com/v1/users/analytics_service_account/tokens/", headers={"Authorization": "Bearer "}, ) response.raise_for_status() ``` ## Delete a service account Deleting a service account immediately revokes its tokens and permanently deletes data owned by that account. :::warning[This action can't be undone] Verify the service account username before deleting it. Data and users deleted through the API can't be recovered. ::: ### UI 1. In **Settings** > **Service Accounts**, find the service account. 2. Open the service account's three-dot menu. 3. Click **Delete account**. 4. Confirm the deletion. ### API using curl Use [`DELETE /v1/users/{username}`](/sql-reference/rest-api/users-delete/) to delete a known service account. ```bash curl -X DELETE \ https://api.motherduck.com/v1/users/analytics_service_account \ -H "Authorization: Bearer " ``` ### API using Python Use [`DELETE /v1/users/{username}`](/sql-reference/rest-api/users-delete/) to delete a known service account. ```python import requests response = requests.delete( "https://api.motherduck.com/v1/users/analytics_service_account", headers={"Authorization": "Bearer "}, ) response.raise_for_status() print(response.json()["username"]) ``` ## Related content - [Create and configure service accounts](/key-tasks/service-accounts-guide/create-and-configure-service-accounts/) - [Impersonate service accounts](/key-tasks/service-accounts-guide/impersonate-service-accounts/) - [MotherDuck REST API](/sql-reference/rest-api/motherduck-rest-api/) --- Source: https://motherduck.com/docs/key-tasks/service-accounts-guide/index # Service accounts > Learn how to create, configure, manage, and impersonate MotherDuck service accounts. Service accounts are non-human user identities for workloads that need to connect to MotherDuck without using a person's credentials. Use these guides to create service accounts, configure their Ducklings, manage tokens, and troubleshoot through UI impersonation. ## Included pages - [Create and configure service accounts](https://motherduck.com/docs/key-tasks/service-accounts-guide/create-and-configure-service-accounts): Learn how to create service accounts, create access tokens, and configure Duckling resources. - [Impersonate service accounts](https://motherduck.com/docs/key-tasks/service-accounts-guide/impersonate-service-accounts): Use UI impersonation to troubleshoot and inspect resources as a service account. - [Manage service accounts and tokens](https://motherduck.com/docs/key-tasks/service-accounts-guide/manage-service-accounts-and-tokens): Use the MotherDuck UI and REST API to view, delete, and rotate service account tokens. --- ## 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%2Fservice-accounts-guide%2F&page_title=MotherDuck%20Documentation%20-%20Service%20accounts&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.