Managing Service Accounts
This guide walks you through the process of creating service accounts, their associated access tokens, and configuring compute instances with the MotherDuck UI or programmatically with the MotherDuck Admin REST API.
Prerequisites: All actions described below are only available to Admin users in your MotherDuck Organization.
API calls must be authenticated using an access token generated by an Admin user in your MotherDuck Organization. Pass this token in the Authorization
header as Bearer YOUR_ADMIN_TOKEN
.
Overview
This guide involves three main steps:
- Create a Service Account: Use the "Create new user" endpoint.
- Create an Access Token: Generate an access token for the newly created service account.
- Configure Instances: Set the type of read-write and read-scaling compute instances for the service account.
Step 1: Create a New Service Account
- UI
- API
-
Navigate to the MotherDuck Web UI -> Settings -> Service Accounts
-
Click Create service account
-
Enter a username for the account (username can only contain characters, numbers, and underscores)
To create a service account, you will use the Create New User (service account) endpoint (the exact endpoint is POST /v1/users
).
Refer to the endpoint documentation for full details on request parameters and responses.
Key details:
- You will define a
username
for your service account. - Important: For all subsequent API calls and identification, use the
username
you defined.
Example of how to call this endpoint using curl
:
curl -X POST \
https://api.motherduck.com/v1/users \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"username": "my-service-account-001",
}'
Step 2: Create an Access Token for the Service Account
- UI
- API
-
Click on the service account username to open details
-
Click Create token
-
Provide a token name
-
For organizations on the Business plan, select a token type. Select Read Scaling Token to leverage MotherDuck's Read Scaling feature
-
(Optional) Select Automatically expire this token to set the token's time-to-live
-
Click Create token. Immediately copy the token from the modal and store it securely. It won't be shown again once the modal is closed
Additional tokens can be created at any time from the service account's details.
Once the service account is created, you should generate an access token for it using the Create an Access Token endpoint (the exact endpoint is POST /v1/users/:username/tokens
).
Refer to the endpoint documentation for full details.
Key details:
- The
:username
in the path refers to theusername
you chose in Step 1 (e.g.,my-service-account-001
). - The path parameter
:username
is a placeholder; replace it with the actual username. For example,/v1/users/my-service-account-001/tokens
. - The
token_type
should be set only if you are on the business plan and want to leverage MotherDuck's Read Scaling feature
Example curl
command:
curl -X POST \
https://api.motherduck.com/v1/users/my-service-account-001/tokens \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "token-for-my-service-account-001",
// "ttl": 300 -- Optional parameter: token time-to-live in seconds (e.g., 5 minutes).
// When ttl parameter is omitted token will not be set to expire
"token_type": "read_write" // Or "read_scaling"
}'
The response will contain the access token for your service account. Securely store this token as it will be used by your service account to authenticate with MotherDuck.
Step 3: Set Account Instances (Configure Compute)
- UI
- API
-
Set the read/write instance size for the account using the dropdown under the Read/Write Instance header
-
For organizations on the Business plan using read scaling, set the account's read scaling instance size and replica pool size using the respective dropdowns.
To define the type of compute instances provisioned for the service account, use the "set user instances" endpoint. (The exact endpoint is PUT /v1/users/:username/instances
).
Refer to the Set User Instances endpoint documentation for details on the correct payload and available instance types.
Key details:
- The
:username
in the path is the service account:username
from Step 1. - This endpoint is used to set both read-write and read-scaling instances
- You always need to pass the entire body, even though you are only interested in changing only one of the two instances configs
Example curl
command:
curl -X PUT \
https://api.motherduck.com/v1/users/my-service-account-001/instances \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"config": {
"read_write": {
"instance_size": "jumbo"
},
"read_scaling": {
"instance_size": "pulse",
"flock_size": 16
}
}
}'
Summary
By following these steps, you can create and configure service accounts for your MotherDuck organization. Remember to:
- Use an Admin account or token for all management operations.
- Securely store the generated service account tokens.
- Use the chosen service account
username
in any API calls.
The REST API methods for managing service accounts are in 'Preview' and may change in the future.
For detailed information on each API call, always refer to the specific endpoint documentation.
Impersonate Service Accounts (UI Only)
- UI
- DuckDB Client API or CLI
Admin users can log into the MotherDuck UI as a service account in the organization using the Impersonation feature. Impersonation allows admins to view and interact with the MotherDuck Web UI by impersonating the service account, which is useful for manually performing read-write actions, monitoring ongoing query activity, or testing and troubleshooting service account-specific resources.
-
Click the trident (⋮) next to the service account you want to impersonate
-
Select Impersonate this account from the dropdown
-
The MotherDuck UI will refresh, and you will be logged into the MotherDuck Web UI as that service account. While impersonating, a persistent banner will be shown at the top of the UI, with options to Refresh session or Return to admin
-
Impersonation sessions expire after two hours. Refresh the browser tab to reset the expiry countdown
You can bookmark the URL while in an impersonation session to generate a new impersonation session using that same service account at a future time.
You must be logged into the MotherDuck Web UI as an Admin user for the URL to successfully start a new impersonation session.
Service account impersonation is currently only available through the MotherDuck Web UI. Use service account tokens to authenticate with service accounts outside of the MotherDuck Web UI.
Managing Service Accounts and Tokens
- UI
Navigate to the MotherDuck Web UI -> Settings -> Service Accounts
Accounts
- New service accounts can be created by clicking the Create service account button above the account list
- The compute instance settings for each account can be managed using the instance and pool size dropdowns in the list
- To view a service account's tokens and details, click the account's username in the list, or click the trident (⋮) next to the service account, and select View details
- Service accounts can be deleted by clicking the trident (⋮) next to the service account, and selecting Delete account
- When a service account is deleted, all tokens associated with the service account are immediately revoked
Tokens
- To view a service account's tokens, click the account's username in the list, or click the trident (⋮) next to the service account, and select View details
- Each valid token for a service account and its type (Read/Write or Read Scaling), creation time, and expiry time is listed in the service account details
- To revoke a token for a service account, click the three-dots (…) next to the token, and select Revoke token. A confirmation prompt will appear, select Revoke token