DBX Team Files Guide

// By Dropbox Platform Team • Dec 07, 2020

Introduction

Dropbox Business brought the power of Dropbox to organizations and teams. Working with team content is slightly different than managing personal content. This document will guide you through the many capabilities of the Dropbox API to manipulate team content.

If you are relatively new to the Dropbox API, we strongly recommend going through the File Access Guide and the Sharing Guide prior to this guide.

There are specific endpoints to interact with team features, and some important things to know when accessing team member files. In this guide we are going to cover the main API operations that involve team files and related concepts such as Namespaces, Select-User, Select-Admin, and Path Root headers.

Interacting with Team Content

If you have ever used a personal Dropbox account, you know that you get your own private space to store and organize your content. In this space you can store files, create folders, and decide whether you are sharing those with other people.

In a Dropbox Business account, in addition to users’ own private spaces, there are organization-managed spaces. These team content repositories are managed by the team administrators. This makes it easier for teams to collaborate and manage their content. Organizations can create folder structures for departments, locations, or projects depending on how they organize their information. Then team administrators can control who has access to each of these folders. There are many advantages to leveraging team repositories, and you can learn about them in the help center article called “Your team space”.

Team Folders and Team Spaces

Dropbox Business Teams will have this organization-managed space in the form of either Team Folders or Team Spaces. The user experience and administration of these two structures varies slightly - as does how to work with them programatically.

Most notably, applications that need to access content within Team Spaces will need to take additional steps with calls in the User API, as described below.

As a developer, you want to make sure your app works in any Dropbox Business account that it connects to, regardless of the folder structure. To guarantee that, you’ll need to understand the two types of organizational models you may encounter in Dropbox teams.

Before we examine the characteristics of each model, we’ll need to introduce the concept of namespaces and rooting

Namespaces

Namespaces are objects that can be accessed through the API. You can think of a namespace as a unique permission space that stores files and folders. Each user's private Dropbox folder maps to a home namespace. Shared folders, team spaces and team folders in Dropbox Business, are each also mapped to namespaces. When a user joins a shared folder it is mounted in their home namespace. In other words, a special folder entry is added to the user's home namespace that points to the shared namespace.

Let's take a look at how namespaces are organized differently in Team Spaces and Team Folders. In the example below, Sarah and John, are both members of the Acme organization that has a Team Folders Dropbox team. The numbers in parenthesis represent the namespace IDs:

Team Folders layout in Dropbox

Team Folders model

Namespace ID Folder Description
1 Sarah's home folder
2 Shared folder between Sarah and John mounted differently in each
user's 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

Now, if their Dropbox team has Team Spaces, the team space will be structured as a root that contains all of the users' folders, and any team folders. This is what Sarah and John's content would be organized:

Team Spaces layout in Dropbox

Team Spaces model

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

API Call Roots

When you issue calls with the Dropbox API, the API calls that reference a specific file’s path are limited to the permissions authorized by the access token and relative to the namespace that the call is rooted to.

For an application with App Folder access, the call is rooted to a folder within the team member’s folder. For an application with Full Dropbox access, the call is rooted to the team member’s folder by default.

In the example image above, if a Full Dropbox app authorized by John executed /files/list_folder - it would be relative to namespace (6), and allow traversal content within that namespace. If John’s team uses Team Folders, this would include the Marketing Team Folder (4) he has access to. If the team uses Team Spaces, this would not include the Marketing Folder (4) within the team space - as it rooted to the Acme Dropbox (7).

Thus if a caller wished to access the Team Space, they would need to root their calls to the Acme Dropbox (7). This would allow the app to access content accessible to and authorized by John - which would include the member folder and other folders he has access to in the team space. Data that John does not have permissions for, like Sarah’s folder (1), would not be visible or accessible.

To root a call to a specific namespace, a caller would need to identify that namespace and indicate it as a target root, as described in the sections below. 

Identifying Root Namespaces

In order to access files on users’ namespaces, first you need to retrieve the namespace IDs from the API. This is done with the endpoint /users/get_current_account.

In the example above, let's call this endpoint with Sarah's user ID. If her team uses Team Folders, we'd get a response like this:

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

Note that root_namespace_id and home_namespace_id are the same. The root of her Dropbox content is her home folder. Now if Sarah's team was on Team Spaces, the response would look like this:

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

In Team Spaces, the root of Sarah’s team namespace is different than her home folder’s namespace. Team shared folders are mounted under namespace (7). Her content and shared folders are mounted under namespace (1).

Using the Dropbox-API-Path-Root Header

The Dropbox-API-Path-Root header can be used to perform actions relative to a namespace. 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. This enables applications to access content in the Team Space, or to root to a particular namespace for syntactic convenience.

In the example above, setting the path Dropbox-API-Path-Root to the company root with a token authorize to John’s account with Team Spaces would return all content he has access to:

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": "7"}' \
    --data '{"path":"/"}'

Response:

{
  ...,
  "path_display": "/John",
  "path_lower" : "/john",
  "name" : "Draft Presentation",
  "parent_shared_folder_id": "7"
  ...,
  "path_display": "/Marketing",
  "path_lower" : "/marketing",
  "name" : "Draft Presentation",
  "parent_shared_folder_id": "7"
}

Remember, users with existing Dropbox accounts may join teams - causing their root folder to change (while their home folder stays the same). The path root header has alternate modes to help your application detect this change. See the Authentication Types Guide for more information.

Managing Team Member Content

So far we have covered accessing content in company managed spaces with the User API. The Business API enables team administrators to both manage company owned spaces, as well as to manage the content of individual team members.

Applications that authorize team scopes receive a team-linked token for operating on Business API endpoints. These applications may also use any authorized User API calls to operate on behalf of members of the team by specifying the member ID in an HTTP header as long as the application has the team_data.member scope. Apps using the legacy permission model must instead select the access type of ‘Team member file access’.

Dropbox-API-Select-User

This header, when used with a team token, enables the application to issue calls on behalf of the specified team member. This enables applications to organize and act on content within users member folders.

Dropbox-API-Select-Admin

This header, when used with a team token, enables the application to issue calls as the specified team administrator.

Select-Admin is required when making modifications to team-managed Team Folders & Team spaces using sharing API calls, as described in the next section.

When reading content and metadata, using Select-Admin enables the caller to see any team accessible content - without needing to determine which user on the team has view access. Using the /team/namespaces/list call to enumerate all team namespaces, then traversing them with /files/list_folder with the Dropbox-API-Select-Admin header enables an app to efficiently enumerate all team content.

Remember, files can be referred to in path arguments by their relative path, file id, revision id, or by a namespace-relative path. While most user-linked applications will prefer referring to files by id or relative path, team linked applications looking to efficiently traverse all team-owned content will tend to find namespace-relative paths simpler.

Read more about how to use these headers in our Authentication Types Guide.

Managing Team Folders and Spaces

Team Folders and Spaces are the best way to organize and control content that belongs to the organization and not to specific users.

Determining the Team's Organizational Model

When reading or writing files to Team Folders or Team Spaces, the methodology is the same–specifying the Dropbox-API-Path-Root allows an application to access all authorized content in both models.

However, a team-linked application that wishes to create and modify these team-managed spaces may need to utilize different API calls to do so, and thus will first need to programmatically determine which model the team is using.

In the Dropbox web interface, it is easy to identify if your team is using Team Spaces: your team member folder is purple and is named after you.

Programmatically, there are a few ways of finding out which type of team you have:

  • If using a team linked app, use the /team/features/get_values endpoint to check the has_team_shared_dropbox boolean. If true, then the team uses the Team Spaces configuration.
  • If using a user linked app, call /users/get_current_account and check the returned RootInfo type to see if the user is a member of a team that uses the team space configuration. Specifically, the returned root_info will be a UserRootInfo (with .tag of user) if the team doesn't use the team space, or a TeamRootInfo (with a .tag of team) if it does.
  • Calling the /team/team_folder/list operation will return a single team folder with the is_team_root boolean set to true, when a team has Team Spaces.

Managing Team Folders

Creating Team Folders

If the team is using Team Folders and you need to create one, you are going to use the /team/team_folder/create Business endpoint. When you create a team folder programmatically, it doesn't give access to anyone automatically, not even to the Dropbox Team administrators. You will need to add members to the Team Folder and configure its security settings after the folder has been created.

If the team is using Team Spaces, and you try to issue the /team/team_folder/create call, you're going to get an error message. We cover managing Team Spaces in the next section.

Managing Team Folder Access

Since Team Folders are managed by Dropbox Team Administrators only, you will need to specify the admin ID that will be executing these operations via the Dropbox-API-Select-Admin header.

Each Team Folder can have different security settings. For example, you may want to create a Team Folder with content that can be shared externally and another Team Folder with content that is sensitive and should be internal only. This can be achieved by configuring the Shared Folder Policy.

Update Folder Policy

The Team Folder security settings can be configured using the endpoint /sharing/update_folder_policy. This is similar to what a Dropbox administrator can do with the Settings of a shared folder. The UpdateFolderPolicyArg object allows you to configure parameters such as:

  • member_policy: who can be invited to this folder (team members only or any Dropbox user)
  • acl_update_policy: who can invite/remove people to this folder (owner only or any member with editor access to the folder)
  • viewer_info_policy: if Viewer Info is enabled or disabled
  • shared_link_policy: who can view shared links on this folder (only team members or anyone)

For the full list of parameters please consult the HTTP endpoint documentation.

Adding people to team folders

The recommended access control practice is to use groups to assign permissions to team folders. This makes the security administration and maintenance a lot easier. In fact with Team Folders you cannot add individual users directly to the root folder, you are required to use groups. You can create groups via the API, add people, and then assign these groups to folders. Check the +Developer Guide - Team Administration guide for information on how to manage groups.

To add a group to a Team Folder use the /sharing/add_folder_member endpoint, the .tag parameter dropbox_id and the group’s unique identifier as the value for dropbox_id.

Restricted access control lists

When you apply permissions to a team folder, by default all the folders in the hierarchy under that folder inherit the same permissions. But you can disable the inheritance and nest folders inside of a team folder or team space with different levels of permissions. Subfolders can have more restricted permissions than their parent folders.

To disable the inheritance, follow these guidelines:

Once the inheritance is disabled, set your desired level of access with /sharing/add_folder_member.

Restoring inheritance:

Deleting Team Folders

Because Team Folders contain information that is accessed by many people, you cannot just outright delete them. You need to first archive the team folder (/team/team_folder/archive), which makes it unavailable for users, and then permanently delete it (/team/team_folder/permanently_delete). Note that not even Dropbox Support can revert a permanent deletion. Archived folders can always be unarchived by using /team/team_folder/activate.

Managing Team Spaces

On Team Folders teams, you have to use the Business API to create and set up Team Folders. But on teams with Team Spaces, you use the same User API calls to work both with shared folders that are mounted under a user-owned namespace (also known as member folder), and with team folders that are mounted on the Team Spaces namespace.

For team-linked apps that need to manipulate Team Spaces folders, you’ll need both Dropbox-API-Path-Root and Dropbox-API-Select-Admin headers. If you don’t specify the path root header, you won’t see team space content. Instead, you’ll be rooted to the user’s member folder rather than the Team Space.

Creating folders on Team Spaces

To create a folder for the team under the Team Space, you can use the /sharing/share_folder endpoint. When you use this endpoint and the folder doesn't exist yet, it will be created. 

A few important things to note here when using it in Team Spaces:

  • The Dropbox-API-Path-Root header can use one of the syntaxes described above in the Dropbox-API-Path-Root Header Modes section, to set this to the root namespace. 
  • The Dropbox-API-Select-Admin is the member ID of an admin, with the syntax dbmid:xxxxx
  • The path parameter defines the name of the folder to be shared/created. It always starts with a slash (‘/’) character.

Additional Resources


// Tags
// Copy link