Manage service accounts and 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.

Admin access required

Managing service accounts and service account tokens requires an organization Admin. REST API examples use 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
View tokens for a known service account	Yes	Yes, with GET /v1/users/{username}/tokens
Create a token for a known service account	Yes	Yes, with POST /v1/users/{username}/tokens
Revoke a known token	Yes	Yes, with DELETE /v1/users/{username}/tokens/{token_id}
Delete a known service account	Yes	Yes, with DELETE /v1/users/{username}
View or configure Ducklings for a known service account	Yes	Yes, with the Duckling configuration endpoints
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

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 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 to list tokens for a known service account username.

curl -X GET \
  https://api.motherduck.com/v1/users/analytics_service_account/tokens \
  -H "Authorization: Bearer <admin_token>"

API using Python

Use GET /v1/users/{username}/tokens to list tokens for a known service account username.

import pprint
import requests

response = requests.get(
    "https://api.motherduck.com/v1/users/analytics_service_account/tokens",
    headers={"Authorization": "Bearer <admin_token>"},
)

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

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} to revoke a known token.

curl -X DELETE \
  "https://api.motherduck.com/v1/users/analytics_service_account/tokens/<token_id>" \
  -H "Authorization: Bearer <admin_token>"

API using Python

Use DELETE /v1/users/{username}/tokens/{token_id} to revoke a known token.

import requests

response = requests.delete(
    "https://api.motherduck.com/v1/users/analytics_service_account/tokens/<token_id>",
    headers={"Authorization": "Bearer <admin_token>"},
)

response.raise_for_status()

Delete a service account

Deleting a service account immediately revokes its tokens and permanently deletes data owned by that account.

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} to delete a known service account.

curl -X DELETE \
  https://api.motherduck.com/v1/users/analytics_service_account \
  -H "Authorization: Bearer <admin_token>"

API using Python

Use DELETE /v1/users/{username} to delete a known service account.

import requests

response = requests.delete(
    "https://api.motherduck.com/v1/users/analytics_service_account",
    headers={"Authorization": "Bearer <admin_token>"},
)

response.raise_for_status()
print(response.json()["username"])

Related content

• Create and configure service accounts
• Impersonate service accounts
• MotherDuck REST API