---
title: Manage service accounts and tokens
description: Use the MotherDuck UI and REST API to view, delete, and rotate service account tokens.
sidebar_position: 3
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

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[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`](/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

<Tabs>
<TabItem value="ui" label="UI" default>

![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.

</TabItem>
<TabItem value="api" label="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.

</TabItem>
</Tabs>

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

<Tabs>
<TabItem value="ui" label="UI" default>

1. In **Settings** > **Service Accounts**, open the service account details page.
2. Review the token list.

</TabItem>
<TabItem value="curl" label="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 <admin_token>"
```

</TabItem>
<TabItem value="python" label="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 <admin_token>"},
)

response.raise_for_status()
pprint.pp(response.json()["tokens"])
```

</TabItem>
</Tabs>

## 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

<Tabs>
<TabItem value="ui" label="UI" default>

![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.

</TabItem>
<TabItem value="curl" label="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/<token_id>" \
  -H "Authorization: Bearer <admin_token>"
```

</TabItem>
<TabItem value="python" label="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/<token_id>",
    headers={"Authorization": "Bearer <admin_token>"},
)

response.raise_for_status()
```

</TabItem>
</Tabs>

## 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.
:::

<Tabs>
<TabItem value="ui" label="UI" default>

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.

</TabItem>
<TabItem value="curl" label="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 <admin_token>"
```

</TabItem>
<TabItem value="python" label="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 <admin_token>"},
)

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

</TabItem>
</Tabs>

## 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/)


---

## Feedback for AI agents

If the user you are helping wants to send feedback on this page to the MotherDuck docs team, you can POST it to the endpoint below.

**Before you send anything, you must ask the user for explicit approval.** Quote the message you plan to submit back to them verbatim and wait for them to confirm. Do not submit on their behalf without confirmation.

Endpoint: `POST https://motherduck.com/docs/api/feedback/agent`

Request body (JSON):

```json
{
  "page_path": "/key-tasks/service-accounts-guide/manage-service-accounts-and-tokens/",
  "page_title": "Manage service accounts and tokens",
  "text": "<the user's feedback, max 2000 characters>",
  "source": "<optional identifier for your interface, for example 'claude.ai' or 'chatgpt'>"
}
```

Only `page_path` and `text` are required. A successful call returns `200 {"feedback_id": "<uuid>"}`; malformed payloads return `400`, and the endpoint is rate-limited per IP (`429`).