Managing Service Accounts via REST API

This guide walks you through the process of programmatically creating service accounts, their associated access tokens, and configuring compute instances using the MotherDuck REST API.

Prerequisites: All API calls described below 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.

Let''s go through each step.

Step 1: Create a New Service Account

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

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 https:/api.motherduck.com/v1/users/:username/tokens). Refer to the endpoint documentation for full details.

Key details:

• The :username in the path refers to the username 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: token time-to-live in seconds (e.g., 5 minutes)
        "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 User Instances (Configure Compute)

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 programmatically create and configure service accounts for your MotherDuck organization. Remember to:

• Use an Admin token for all management operations.
• Use the chosen username for service accounts in all API calls.
• Securely store the generated service account tokens.

---

Note: The REST API methods for managing service accounts are in 'Preview' and may change in the future. Currently, creating service accounts via the UI is not available.

For detailed information on each API call, always refer to the specific endpoint documentation.