DBX Team Files Guide

// By Dropbox Platform Team • Dec 07, 2020

Introduction

Dropbox for teams 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.

We will also cover the difference between the team folder and team space configurations, as well as what happens when teams are migrated from team folders to team spaces.

Interacting with Team Content

Each Dropbox team may use one of two different configurations: team folders or team space. Team content is structured differently in each one, and that can affect how you use the Dropbox API to interact with team content.

In the team folder configuration, team folders are mounted in member folders:

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 the team space configuration, the team space will be structured as a root that contains all of the users' folders, and any team folders. This is how 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.
  • Teams using the team folders configuration may be migrated to use a team space, resulting in team folders being moved to the team space.

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 an app 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 the team folders configuration, this would include the Marketing team folder (4) he has access to. If the team uses the team space configuration, this would not include the Marketing folder (4) within the team space, as it is 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 the team folders configuration, 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 the team space configuration, the response would look like this:

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

In a team space, 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 this example, setting the path Dropbox-API-Path-Root to the company root with a token authorized to John’s account with a team space would return all content he has access to:

curl -X POST https://api.dropboxapi.com/2/files/list_folder \
    --header 'Authorization: Bearer <token>' \
    --header 'Dropbox-API-Path-Root: {".tag": "root", "root": "7"}' \
    --header "Content-Type: application/json" \
    --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 Path Root Header Modes documentation for more information.

Using the Dropbox-API-Path-Root header is recommended as it works for both configurations. If you don’t set the Dropbox-API-Path-Root header, your app will not be able to access the contents of the team space (for any connected users with the team space configuration).

The official Dropbox SDKs also offer support for setting the Dropbox-API-Path-Root header. If you’re using an official Dropbox SDK, refer to the respective documentation 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.

Dropbox-API-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 Dropbox-API-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 the team space configuration: 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 it's true, then the team uses the team space 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 a team space.

If you need a Dropbox team to develop and test your integration and don’t already have one, refer to the “How do I test my application?” question under “Frequently Asked Questions” on the support page.

Managing Team Folders

Creating Team Folders

If the team is using the team folders configuration and you need to create a new team folder, you are going to use the /team/team_folder/create 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 the team space configuration, 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 teams with the team folders configuration, you have to use the Business API to create and set up team folders. But on teams with the team space configuration, 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 space namespace.

Attempting to use the team_folder/activate, team_folder/archive, team_folder/create, team_folder/permanently_delete, team_folder/rename, or team_folder/update_sync_settings endpoints for a team with a team space will fail with either an team_shared_dropbox_error/disallowed or invalid_account_type/feature error. Calling team_folder/get_info and team_folder/list for a team with a team space will only return information about the team space.

For team-linked apps that need to manipulate team space 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 the team space configuration:

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

FAQ

  • What happens when a team is migrated from the team folders configuration to a team space?
    • When a team is migrated from team folders to a team space, the team folders will be moved from the member folders to the new team space. You can find more information in this help center article.
  • When happens if an app isn’t updated to support accessing the team space and a team is migrated to use a team space?
    • When a team is migrated to use the team space configuration, team folders are moved to the team space. By default, without setting the Dropbox-API-Path-Root header, API calls will operate in the member folder and will no longer return those team folders. If an app is relying on absolute paths to team folders in the member folders and doesn’t set the Dropbox-API-Path-Root header, those team folders will no longer be found at those paths when the team is migrated, causing those API calls to fail.
  • Does a team’s namespace IDs change during the migration to the team space configuration?
    • Existing team folders and shared folders keep their existing namespace IDs through the migration. The new team space itself is given a new distinct namespace ID.
  • How can I check which configuration my own team currently uses?
    • You can manually check which configuration your team uses via the Dropbox web site. Refer to this help center article for instructions on how to do so. To programmatically check which configuration a team is currently using via the API, refer to the "Determining the Team's Organizational Model” section above.
  • How can I list the contents of the team space programmatically?
    • To list the contents of the team space itself, use /files/list_folder with the Dropbox-API-Path-Root header set to the team space as root and set the path to "". Refer to the “Using the Dropbox-API-Path-Root Header” section above for more information.

Additional Resources


// Copy link