Skip to navigation

Workspaces

A workspace is a set of access rules over a user's files, not a separate container or copy.
View as Markdown

Effective access

All four layers must allow an operation:

  1. App permissions.
  2. User-token and agent-token OAuth scopes.
  3. The user’s access to the file.
  4. The agent’s workspace role.

User permissions are the ceiling. Scopes and workspace rules can only narrow access.

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.
  • Folder rules apply to descendants; a more specific rule takes precedence.
  • No matching rule means access is denied.
  • Edits leave omitted rules unchanged and apply to active and new tokens.

Use "" for the root in API requests; "/" is rejected. The CLI accepts / and translates it. Root responses use an empty path.

For deleted or no-longer-visible items, responses may omit path. Remove such rules by file_id.

CLI paths

CLI workspace and mounted paths are relative to the account root:

Use /Projects/build-output directly; do not add a member folder name.

Use an id: value for a stable reference across moves or renames. Direct API paths use Dropbox-API-Path-Root; without it, they are relative to the user’s home namespace.

Mounted path example

After writing /Projects/build-output/result.txt through a personal-account agent mount at /workspace/agent-files, the mounted path is:

/workspace/agent-files
Projects
build-output
result.txt

User permissions

Use standard Dropbox sharing APIs: sharing/share_folder creates a shared folder; sharing/add_folder_member adds members.

Sharing changes user access, not agent workspace rules. Update a workspace separately when an agent also needs access.

See Sharing and File Operations.