Path Root Header Modes

When using the Dropbox User API, calls that access content are “rooted” to a particular directory per the apps permission. This means that relative paths are evaluated relative to this location, and paths outside of this location are not accessible. For apps that request App Folder access, these calls are rooted to the app folder. For applications that request Full Dropbox access, these calls are rooted to the User’s Dropbox folder by default.

Apps may also pass an additional HTTP header, Dropbox-API-Path-Root, in conjunction with authorization hearers to change where calls are rooted to, as allowed per the app’s permission. An application may wish to root to a frequently used shared folder for convenience, but the most common use case for doing so is to access the Team Space, which are special team managed folders available to some Dropbox Business teams. Refer to the DBX Team Files Guide for more information.

The Dropbox-API-Path-Root header supports three different modes.

Home

Sample Syntax:

 --header 'Dropbox-API-Path-Root: {".tag": "home"}

This will perform all actions relative to the user’s home_namespace_id as identified by /users/get_current_account. At the time of writing, this is the same as the default behavior when the Dropbox-API-Path-Root header is not included.

Root

Sample Syntax:

 --header 'Dropbox-API-Path-Root: {".tag": "root", "root": "7"}

The intent of the root mode is to guarantee the namespace_id specified as the root is indeed the root for that user, as identified by the root_namespace_id returned by /users/get_current_account. The namespace ID for a user's "root" can change if the user joins, leaves, or changes teams. This mode will test whether the namespace ID passed in as the root is the correct root namespace for the user. If this value does not match the user’s root_namespace_id, a 422 error will be returned.

When using root mode, the app should catch this error and perform any logic necessary to account for the change to the user’s root namespace. Note that the error body will include a root_namespace_id that indicates the updated namespace ID for the user account.

Sample Request:

curl -X POST https://api.dropboxapi.com/2/files/list_folder \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Dropbox-API-Path-Root: {".tag": "root", "root": "1"}' \
  --data '{"path":""}'

Sample Error:

{
  "error_summary": "invalid_root/..",
  "error": {
    ".tag": "invalid_root",
    "invalid_root": {".tag": "user", "root_namespace_id": "7"}
  }
}

Namespace

Sample Syntax:

 --header 'Dropbox-API-Path-Root: {".tag": "namespace_id", "namespace_id": "2"}

Using namespace_id will perform all actions relative to the specified namespace. A 422 error response will be returned if the user is accessing a namespace ID that either does not exist or the user does not have permission to access. This mode allows rooting to any namespace according to the authorized permissions of the access token.

Sample Request:

curl -X POST https://api.dropboxapi.com/2/files/list_folder \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Dropbox-API-Path-Root: {".tag": "namespace_id", "namespace_id": "10"}' \
  --data '{"path":""}'

Sample Error:

{
  "error_summary" : "no_permission/..",
  "error" : {
   ".tag" : "no_permission"
  }
}