---
title: Agent Data Services Access Control (private)
description: DigitalOcean Agent Data Services uses team roles, API token scopes, and workspace-scoped tokens to control who can manage workspaces and data flows …
product: Agent Data Services
url: https://docs.digitalocean.com/products/agent-data-services/details/access-control/
last_updated: "2026-10-12"
---

> **For AI agents:** The documentation index is at [https://docs.digitalocean.com/llms.txt](https://docs.digitalocean.com/llms.txt). Markdown versions of pages use the same URL with `index.html.md` in place of the HTML page (for example, append `index.html.md` to the directory path instead of opening the HTML document).

# Agent Data Services Access Control (private)

DigitalOcean Agent Data Services is a fully managed service that turns raw multimodal and behavioral data into AI-ready data that you can query as soon as it arrives.

DigitalOcean Agent Data Services uses DigitalOcean IAM to control two kinds of access: managing Agent Data Services resources, such as workspaces and data flows, and querying the data in a workspace. A token that you use day to day usually needs both: management scopes to find and operate resources, and query access to retrieve data.

The Agent Data Services scopes appear in the token creation flow only for teams with access to the [private preview](https://docs.digitalocean.com/platform/product-lifecycle/index.html.md#private-preview).

## Agent Data Services Token Scopes

You can add the following Agent Data Services scopes when you [create a personal access token with custom scopes](https://docs.digitalocean.com/reference/api/create-personal-access-token/index.html.md). Scope names, API paths, and request fields use `sandbox`, an earlier name for a workspace, and `pipeline`, an earlier name for a data flow.

| Scope | Grants |
|---|---|
| `aidc_sandbox:create` | Create workspaces. |
| `aidc_sandbox:read` | View workspaces and their configuration. Also required to create workspace-scoped query tokens. |
| `aidc_sandbox:update` | Update workspace configuration. |
| `aidc_sandbox:delete` | Delete workspaces. |
| `aidc_pipeline:create` | Create data flows. |
| `aidc_pipeline:read` | View data flows. |
| `aidc_pipeline:update` | Update data flows. |
| `aidc_pipeline:delete` | Delete data flows. |
| `aidc_pipeline:operate` | Start and stop data flows. |
| `aidc_query:create` | Create query configuration for a workspace. |
| `aidc_query:update` | Update query configuration for a workspace. |
| `aidc_query:delete` | Delete query configuration for a workspace. |
| `aidc_query:read` | Run queries against workspaces. |
| `aidc_query:view_credentials` | View query credentials for a workspace. |

Each `create`, `update`, `delete`, and `operate` scope requires the `read` scope in the same group. For example, a token with `aidc_pipeline:operate` also needs `aidc_pipeline:read`. Because `aidc_query:read` grants query access, any token that can change query configuration can also run queries.

The `aidc_sandbox:*` scopes let you manage workspaces but do not let you query them. To query a workspace, a token needs `aidc_query:read`.

The broad `api:read` scope does not include `aidc_query:read` or `aidc_query:view_credentials`. A read-only token cannot query workspaces or view query credentials unless you add those scopes explicitly.

## Agent Data Services Permissions for Team Roles

[Predefined team roles](https://docs.digitalocean.com/platform/teams/roles/predefined/index.html.md) grant the following Agent Data Services permissions. Team role permissions apply to every workspace in the team.

| Role | Workspaces | Data flows | Queries |
|---|---|---|---|
| **Owner** | Full access | Full access | Full access, including running queries and viewing query credentials |
| **Member** | Create, view, and update | Create, view, update, start, and stop | Create and update query configuration, run queries, and view query credentials |

Members cannot delete workspaces or data flows.

## Query Access to Workspaces

You can grant query access in two ways, depending on how many workspaces the token needs to reach:

- **Team-wide query access:** Create a [personal access token with custom scopes](https://docs.digitalocean.com/reference/api/create-personal-access-token/index.html.md) that includes `aidc_query:read`. The token can query every workspace in the team.
- **Workspace-scoped query access:** Use the Agent Data Services API to create a token that can query only the workspaces you choose. Use workspace-scoped tokens for CI jobs, contractors, and applications that need access to a single environment.

### Create a Workspace-Scoped Query Token

To create a workspace-scoped query token, you need a token with `aidc_sandbox:read` and the UUIDs of the workspaces you want to grant access to. All of the workspaces must be in the same region.

To find your workspace UUIDs, send a `GET` request to the `/sandboxes` endpoint for the region. During private preview, all workspaces are in `mem1`:

```shell
curl -X GET "https://api.digitalocean.com/v2/data-cloud-platform/mem1/sandboxes" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN"
```

To create the token, send a `POST` request to the tokens endpoint for the same region:

```shell
curl -X POST "https://api.digitalocean.com/v2/data-cloud-platform/mem1/tokens" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "TOKEN_PURPOSE_QUERY",
    "sandbox_uuids": ["<workspace-uuid>"],
    "name": "<token-name>",
    "expires_in_seconds": 3600
  }'
```

| Parameter | Required | Description |
|---|---|---|
| `purpose` | Yes | The token purpose. Use `TOKEN_PURPOSE_QUERY`, which is the only supported value during private preview. |
| `sandbox_uuids` | Yes | One or more UUIDs of workspaces in the region. Each workspace must belong to your team and have a provisioned query endpoint. |
| `name` | No | A display name for the token. If you omit it, Agent Data Services generates a name. |
| `expires_in_seconds` | No | The token lifetime in seconds. If you omit it or set it to `0`, the token uses the default lifetime. |

A successful request returns the token ID, name, the token value in `access_token`, and the expiration time in `expires_at`:

```json
{
  "id": "1234567",
  "name": "<token-name>",
  "access_token": "dop_v1_REPLACEME",
  "expires_at": "2026-10-13T18:00:00Z"
}
```

The response is the only time the token value is shown. Store it in a secret manager, and do not log it.

The new token has `aidc_query:read` for the workspaces you listed and no other permissions. It cannot manage workspaces or data flows, and it cannot query workspaces that you did not list.

The request fails if `sandbox_uuids` is empty, if a workspace is not in your team or not in the region in the path, or if a workspace does not have a query endpoint yet.