For AI agents: The documentation index is at 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).

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.

Agent Data Services Token Scopes

You can add the following Agent Data Services scopes when you create a personal access token with custom scopes. Scope names, API paths, and request fields use sandbox, an earlier name for a workspace, and pipeline, an earlier name for a data flow.

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 grant the following Agent Data Services permissions. Team role permissions apply to every workspace in the team.

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

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:

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
  }'

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

{
  "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.