Namespace Guide

This guide covers advanced topics relating to Shared Folders, Team Folders and Team Spaces & Member Folders for Business Accounts. Continue reading for API examples of different ways to access these folders.

What are Namespaces?

From our Data Ingress Guide:

You can think of a namespace as a collection of files and folders in the internal representation of the Dropbox file system. Each user's private Dropbox folder maps to a root namespace. Shared folders and team folders in Dropbox Business and Dropbox Enterprise, are each also mapped to namespaces. When a user joins a shared folder it is mounted in their root namespace. That is, a special folder entry is added to the user's root namespace that points to the shared namespace.

What has a Namespace?

  • • A User's home folder
  • • Shared folders
  • • Team folders
  • • Team Root folder
  • • App folders

In the example below, Sarah and John, are both members of the Acme organization, and have a combination of of folder types in their Dropbox folder:

Namespace ID Folder Description
1 Sarah's home folder
2 Shared folder between Sarah and John mounted differently in each users Dropbox folder (and with a different name).
3 Shared folder that is shared with Sarah only.
4 Acme team folder accessible to both Sarah and John
5 Acme shared folder
6 John's home folder

Team Space

For Business Teams using team space and member folders, the team space will be structured as a root that contains all of the users folder, and any team folders. The same example using Sarah and John from above can be visualized as:

This the addition of the team space and member folders introduces the following changes to our original example:

  • • The Acme Dropbox team root folder is a parent of both Sarah and John's home Dropbox Folders with namespace ID (7).
  • • "Marketing (4)" is a share under the Acme Dropbox team root folder, rather than a team folder mounted to member folders.
  • • Other than the new Namespace ID added to the Acme Dropbox folder, all other namespace IDs are unchanged.

Retrieving Namespace IDs from the API

User's Home Folder & Team Root Folder

The namespace ID for a users home folder and/or team root folder (if the user is a member of a team) are listed as part of users/get_current_account.

curl -X POST https://api.dropboxapi.com/2/users/get_current_account \
    --header 'Authorization: Bearer <token>'

Using the first example above for Sarah, the response body would be as follows:

    {
      ...
      "root_info": {
        ".tag": "user",
        "root_namespace_id": "1",
        "home_namespace_id": "1",
      }
    }

The root_namespace_id and home_namespace_id are identical because the root of Sarah's Dropbox is her home folder.

If Acme Dropbox is using a team space, the response would be:

    {
      ...
      "root_info": {
        ".tag": "team",
        "root_namespace_id": "7",
        "home_namespace_id": "1",
        "home_path": "/Sarah"
      }
    }

In this scenario the root_namespace_id and home_namespace_id differ because the root accessible to Sarah is the Acme Dropbox root folder. The home_namespace_id maps to Sarah's personal folder within the Acme organization.

Shared Folders (User and Team)

All shared folders have a shared_folder_id. This value is identical to the namespace ID for that shared folder. The value is part of the response object for files/list_folder and sharing/list_folders.

    {
      "entries": [
      {
          ".tag": "folder",
          "name": "Sarah-John Share",
          "path_lower": "/sarah-john share",
          "path_display": "/Sarah-John Share",
          "id": "id:123",
          "shared_folder_id": "2",
          "sharing_info": {
            "read_only": false,
            "shared_folder_id": "2"
          }
        }
      ]
    }

Namespaces Accessible to a Team

For team linked apps, the namespaces/list endpoint will list all namespaces associated with the team. This includes namespace IDs for individual team member folders, shared folders, root team folder, and any app folders.

Using a Namespace to Identify Content

As a Value in the path Parameter

Many endpoints take a path parameter. The path parameter supports different syntaxes for accessing files in Dropbox. A full list of supported formats is in the HTTP documentation. For this example, we will use the namespace relative syntax: ns:<namespace id>/<path>. Below are examples of files/list_folder and files/get_metadata based on the example above for Sarah's Dropbox.

curl -X POST https://api.dropboxapi.com/2/files/get_metadata \
    --header 'Authorization: Bearer <token>' \
    --data '{"path":"ns:2/draft presentation"}'
    {
      ...,
      "path_display": "/Sarah-John Share/Draft Presentation",
      "path_lower" : "/sarah-john share/draft presentation",
      "name" : "Draft Presentation",
      "parent_shared_folder_id": "2"
    }

To treat the namespace ID as a folder path, leave off the <path> value.

curl -X POST https://api.dropboxapi.com/2/files/list_folder \
    --header 'Authorization: Bearer <token>'
    --data '{"path":"ns:2"}'
    {
      "entries": [
        {
          ...,
          "path_display": "/Sarah-John Share/Draft Presentation",
          "path_lower" : "/sarah-john share/draft presentation",
          "name" : "Draft Presentation",
          "parent_shared_folder_id": "2"
        }
      ]
    }

Using the Dropbox-API-Path-Root Header

The Dropbox-API-Path-Root header can be used to perform actions relative to a namespace without including the namespace as part of the path variable for every request. When using this header, all operations will be performed as if the specified namespace were the root namespace. Response values like path_display and path_lower will also be relative to the namespace ID.

Here the same examples from above with the namespace specified via the Dropbox-API-Path-Root header.

curl -X POST https://api.dropboxapi.com/2/files/get_metadata \
    --header 'Authorization: Bearer <token>' \
    --header 'Dropbox-API-Path-Root: {".tag": "namespace_id", "namespace_id": "2"}' \
    --data '{"path":"/draft presentation"}'
    {
      ...,
      "path_display": "/Draft Presentation",
      "path_lower" : "/draft presentation",
      "name" : "Draft Presentation",
      "parent_shared_folder_id": "2"
    }
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": "2"}' \
    --data '{"path":""}'
    {
      "entries": [
        {
          ...,
          "path_display": "/Draft Presentation",
          "path_lower" : "/draft presentation",
          "name" : "Draft Presentation",
          "parent_shared_folder_id": "2"
        }
      ]
    }

Dropbox-API-Path-Root Header Modes

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 users 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.

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 access to.

Sample Error:

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":""}'
    {
       "error_summary" : "no_permission/..",
       "error" : {
          ".tag" : "no_permission"
       }
    }

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. The namespace ID for a user's "root" can change if the user joins/leaves/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 users root_namespace_id , a 422 error will be returned.

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

Sample Error:

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":""}'
    {
        "error_summary": "invalid_root/..",
        "error": {
            ".tag": "invalid_root",
            "invalid_root": {".tag": "user", "root_namespace_id": "7"}
        }
    }