Next Friday - Get Started with MotherDuck with a Live Demo and Q&ASave Your Spot

Skip to main content

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.

note

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:

  1. Create a Service Account: Use the "Create new user" endpoint.
  2. Create an Access Token: Generate an access token for the newly created service account.
  3. Configure Instances: Set the type of read-write and read-scaling compute instances for the service account.

Step 1: Create a New Service Account

Service Account UI

  1. Navigate to the MotherDuck Web UI -> Settings -> Service Accounts

  2. Click Create service account

  3. Enter a username for the account (username can only contain characters, numbers, and underscores)

Step 2: Create an Access Token for the Service Account

Service Account UI

  1. Click on the service account username to open details

  2. Click Create token

  3. Provide a token name

  4. For organizations on the Business plan, select a token type. Select Read Scaling Token to leverage MotherDuck's Read Scaling feature

  5. (Optional) Select Automatically expire this token to set the token's time-to-live

  6. 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.

Step 3: Set Account Instances (Configure Compute)

Service Account Instance Size Settings

  1. Set the read/write instance size for the account using the dropdown under the Read/Write Instance header

  2. 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.

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.

note

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)

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.

Service Account Impersonation Option

  1. Click the trident (⋮) next to the service account you want to impersonate

  2. Select Impersonate this account from the dropdown

  3. 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

  4. Impersonation sessions expire after two hours. Refresh the browser tab to reset the expiry countdown

Service Account Impersonation Banner

tip

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.

Managing Service Accounts and Tokens

Navigate to the MotherDuck Web UI -> Settings -> Service Accounts

Service Account Impersonation Option

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 Revoke Token Modal for Service Account