Skip to navigation
Concepts

Workspaces

Limit each agent to selected files and folders
View as Markdown

An agent workspace is a set of access rules. It is not a separate file container or a copy of the user’s content.

Agent Filesystem is in Private Preview and is subject to change. Contact your Dropbox representative to request access.

Effective access

An agent can use a file only when every access layer allows the operation:

  1. The app has the required permission.
  2. The user token and agent token include the required OAuth scope.
  3. The user has access to the file.
  4. The agent’s workspace role allows the operation.

User permissions set the maximum access. Token scopes and workspace rules can reduce that access. They cannot grant access that the user lacks.

Workspace roles

RoleEffect
noneDeny access to the selected item.
readAllow supported metadata and content reads.
read_writeAllow reads and supported content changes.
removeDelete an explicit rule during an edit. This role is not returned when you list the workspace.

A folder rule also applies to its descendants. A more specific rule overrides a broader rule. Access is denied when no rule matches.

Workspace edits leave omitted rules unchanged. Updated rules apply to active and new agent tokens.

In API requests, use "" to edit the root rule; "/" is not accepted as the root path. dbx agent workspace accepts / for the root and translates it to "". The root rule is identified by an empty path in workspace responses. If a file or folder was deleted or is no longer visible, its response may omit path; remove that rule with its file_id.

CLI paths

For team users with a team space, CLI workspace paths and mounted paths are relative to the account root. Include the member folder name when referring to content in that folder. For example, /Projects/build-output in a member’s Dropbox folder may be /Jane Doe/Projects/build-output from the account root. The mount uses that same path beneath its mount point.

For personal accounts, paths are relative to your Dropbox folder and do not include a member folder name. Use /Projects/build-output directly.

You can also use a file or folder’s id: value to grant workspace access without depending on its current path. Direct API requests use the namespace selected by Dropbox-API-Path-Root; without that header, file paths are relative to the user’s home namespace.

User permissions

Control user access with the standard Dropbox sharing APIs. For example, use sharing/share_folder to create a shared folder and sharing/add_folder_member to add members.

Sharing changes the files that the user can access. It does not add those files to an agent workspace. Add or update a workspace rule separately when an agent also needs access.

See Sharing for the full sharing model and File Operations for supported file requests and scopes.