> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.dropboxapi.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.dropboxapi.com/_mcp/server.

# Team Files

\[November 10, 2023 Update: We’ve updated this Team Files Guide to incorporate information about new features and changes to the Dropbox API around accessing team content. You can find more information about these updates in [this blog post](https://dropbox.tech/developers/api-updates-to-better-support-team-spaces).]

## 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](/dropbox-api/docs/file-access) and the [Sharing Guide](/dropbox-api/docs/sharing) prior to this guide.

There are [specific endpoints to interact with team](/dropbox-api/api-reference/business-endpoints/overview)[ features](/dropbox-api/api-reference/business-endpoints/overview), 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](https://help.dropbox.com/organize/team-folders) and [team space](https://help.dropbox.com/organize/team-space-overview) configurations, as well as what happens when teams are [migrated from team folders to team spaces](https://help.dropbox.com/plans/upcoming-business-team-changes).

## Interacting with Team Content

Each Dropbox team may use one of two different configurations: [team folders](https://help.dropbox.com/organize/team-folders) or [team space](https://help.dropbox.com/organize/team-space-overview). Different teams may also have different features enabled, which will affect how your app will need to operate. 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](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/dropbox-api.docs.buildwithfern.com/37b02b2c6697e52359852554013f052b9a138b6215cd3ae244de8527b37bbc61/docs/assets/migrated/team-files/b7b1923fb5.webp?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260912%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260912T064446Z&X-Amz-Expires=604800&X-Amz-Signature=b72a69414c2bb54a5a4f1c3dedfa22b254490313aaad72acdb95c4beabcdda5f&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

| 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](https://www.dropbox.com/help/business/team-space-overview) configuration, the team space will be structured as a root that contains all of the user’s folders, and any team folders they have access to. This is how Sarah and John's content would be organized:

![Team Spaces layout in Dropbox](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/dropbox-api.docs.buildwithfern.com/977cd0a525ea1238b97de3298f5a339753bef579d9f37afc2de0128d6bd15d1e/docs/assets/migrated/team-files/ab4c08675a.webp?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260912%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260912T064446Z&X-Amz-Expires=604800&X-Amz-Signature=6ea9a9277f21bb5518d37344f2506ef284e28f44446a6a889adaeef1cc4e2018&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

* The Acme Dropbox team root folder is a parent of both Sarah and John's home Dropbox Folders with namespace ID (7) if team\_shared\_dropbox is `true`; if it is `false`, then each team member account has its own root.
* "Marketing (4)" is a share under the Acme Dropbox team space, rather than a team folder mounted to member folders.
* The namespace IDs for existing mounted namespaces, such as shared folders, are unchanged.
* Teams using the team folders configuration may be [migrated to use the team space](https://help.dropbox.com/plans/upcoming-business-team-changes) configuration, 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](/dropbox-api/docs/oauth) access, the call is rooted to an app folder within the team member’s folder. For an application with [Full Dropbox](/dropbox-api/docs/oauth) 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](/dropbox-api/api-reference/user-endpoints/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 team space.

Thus if a caller wished to access the team space, they would need to root their calls to the team space for the account. 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](/dropbox-api/api-reference/user-endpoints/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:

```json
{
  ...
  "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 with `has_team_shared_dropbox: true`, the response would look like this:

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

In the team space configuration, the root namespace of Sarah’s account is different than her home namespace. Team content is under her root 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. Response values like `path_display` and `path_lower` will also be relative to that root. 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 `Dropbox-API-Path-Root` to access the root namespace with a token authorized to Sarah’s account with a team space would return content she has access to:

```bash
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:

```json
{
  ...,
  "path_display": "/Sarah/Draft Presentation",
  "path_lower" : "/sarah/draft presentation",
  "name" : "Draft Presentation",
  ...,
  "path_display": "/Marketing",
  "path_lower" : "/marketing",
  "name" : "Marketing",
  ...,
}
```

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](/dropbox-api/docs/technical-reference/path-root-header-modes) 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:

* [SwiftyDropbox `withPathRoot`](http://dropbox.github.io/SwiftyDropbox/api-docs/latest/Classes/DropboxClient.html#/s:13SwiftyDropbox0B6ClientC12withPathRootyAcA6CommonC0eF0OF)
* [Objective-C `withPathRoot`](http://dropbox.github.io/dropbox-sdk-obj-c/api-docs/latest/Classes/DBUserClient.html#/c:objc\(cs\)DBUserClient\(im\)withPathRoot:)
* [Python `with_path_root`](https://dropbox-sdk-python.readthedocs.io/en/latest/api/dropbox.html#dropbox.dropbox_client.Dropbox.with_path_root)
* [.NET `WithPathRoot`](https://dropbox.github.io/dropbox-sdk-dotnet/gh-pages/obj/api/Dropbox.Api.DropboxClient.html#Dropbox_Api_DropboxClient_WithPathRoot_Dropbox_Api_Common_PathRoot_)
* [Java `withPathRoot`](https://dropbox.github.io/dropbox-sdk-java/api-docs/v5.3.0/com/dropbox/core/v2/DbxClientV2.html#withPathRoot\(com.dropbox.core.v2.common.PathRoot\))
* [JavaScript `pathRoot`](https://dropbox.github.io/dropbox-sdk-js/Dropbox.html#Dropbox__anchor)

## Managing Team Member Content

So far we have covered accessing content in company managed spaces with the [Use](/dropbox-api/api-reference)[r API](/dropbox-api/api-reference). The [Business](/dropbox-api/api-reference/business-endpoints/overview)[ API](/dropbox-api/api-reference/business-endpoints/overview) 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](/dropbox-api/docs/oauth) receive a team-linked token for operating on [Business](/dropbox-api/api-reference/business-endpoints/overview)[ API](/dropbox-api/api-reference/business-endpoints/overview) endpoints. These applications may also use any authorized [Use](/dropbox-api/api-reference)[r API](/dropbox-api/api-reference) calls to operate on behalf of members of the team by [specifying the member ID in an HTTP header](/dropbox-api/api-reference/business-endpoints/overview#member-file-access) 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](/dropbox-api/api-reference/business-endpoints/team/namespaces-list) call to enumerate all team namespaces, then traversing them with [/files/list\_folder](/dropbox-api/api-reference/user-endpoints/files/list-folder) with the `Dropbox-API-Select-Admin` header enables an app to efficiently enumerate all team content.

Remember, files can be [r](/dropbox-api/docs/file-access)[eferred to in ](/dropbox-api/docs/file-access)[`path`](/dropbox-api/docs/file-access)[ arguments](/dropbox-api/docs/file-access) 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](/dropbox-api/docs/auth-types).

## 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 and features 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 named after you](https://help.dropbox.com/teams-admins/team-member/team-space-overview).

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](/dropbox-api/api-reference/business-endpoints/team/features-get-values) endpoint to check the `has_distinct_member_homes` boolean. If it's `true`, then the team uses the team space configuration.
* If using a user linked app, call [/users/features/get\_values](/dropbox-api/api-reference/user-endpoints/users/features-get-values) and check the `distinct_member_home` boolean. If it's `true`, then the user’s team uses the team space configuration.

Additionally, there are a few ways to determining which features a team has:

* If using a team linked app, use the [/team/features/get\_values](/dropbox-api/api-reference/business-endpoints/team/features-get-values) endpoint to check the `has_team_shared_dropbox` boolean. If it's `true`, then the team uses a single team space for all members of the team, and the contents can be managed directly in the team space using the [/files](/dropbox-api/api-reference/user-endpoints/files) endpoints. If it’s `false`, then the team’s team folders can be managed using the [/team/team\_folder](/dropbox-api/api-reference/business-endpoints/team/team-folder-list) endpoints.
* If using a user linked app, use the [/users/features/get\_values](/dropbox-api/api-reference/user-endpoints/users/features-get-values) endpoint to check the `team_shared_dropbox` boolean. If it's `true`, then the user’s team uses a single team space for all members of the team, and the contents can be managed directly in the team space using the [/files](/dropbox-api/api-reference/user-endpoints/files) endpoints. If it’s `false`, then user-linked apps cannot create files or folders directly in a team space; files and folders may only be added inside team folders inside 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](https://www.dropbox.com/developers/support).

### Managing Team Folders

**Creating Team Folders**

If the team has `has_team_shared_dropbox: false` and you need to create a new team folder, use the [/team/team\_folder/create](/dropbox-api/api-reference/business-endpoints/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 `has_team_shared_dropbox: true`, and you try to issue the [/team/team\_folder/create](/dropbox-api/api-reference/business-endpoints/team/team-folder-create) call, you're going to get an error message. We cover that scenario in the next section under “Managing Team Spaces”.

**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](/dropbox-api/api-reference/user-endpoints/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](https://help.dropbox.com/files-folders/share/viewer-information) 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](/dropbox-api/api-reference/user-endpoints/sharing/update-folder-policy).

**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 [Team Administration Guide](/dropbox-api/docs/team-administration) for information on how to manage groups.

To add a group to a team folder use the [/sharing/add\_folder\_member](/dropbox-api/api-reference/user-endpoints/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:

* Restrict access to a **new** shared folder by calling [/sharing/share\_folder](/dropbox-api/api-reference/user-endpoints/sharing/share-folder) with `access_inheritance` set to `no_inherit`.
  * Note that [/sharing/share\_folder](/dropbox-api/api-reference/user-endpoints/sharing/share-folder) will create a new folder if given a path that does not exist.
* Restrict access to an **existing** folder by calling [/sharing/set\_access\_inheritance](/dropbox-api/api-reference/user-endpoints/sharing/set-access-inheritance) with `access_inheritance` set to `no_inherit`.

Once the inheritance is disabled, set your desired level of access with [/sharing/add\_folder\_member](/dropbox-api/api-reference/user-endpoints/sharing/add-folder-member).

Restoring inheritance:

* Calling [/sharing/set\_access\_inheritance](/dropbox-api/api-reference/user-endpoints/sharing/set-access-inheritance) with `access_inheritance` set to `inherit` will **restore** all permissions inherited from the parent folder.

**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](/dropbox-api/api-reference/business-endpoints/team/team-folder-archive)), which makes it unavailable for users, and then permanently delete it ([/team/team\_folder/permanently\_delete](/dropbox-api/api-reference/business-endpoints/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](/dropbox-api/api-reference/business-endpoints/team/team-folder-activate).

### Managing Team Spaces

On teams with `has_team_shared_dropbox: false`, you have to use the Business API to create and set up team folders. But on teams with `has_team_shared_dropbox: true`, 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 folders that are mounted in the team space namespace.

Attempting to use the [team\_folder/activate](/dropbox-api/api-reference/business-endpoints/team/team-folder-activate), [team\_folder/archive](/dropbox-api/api-reference/business-endpoints/team/team-folder-archive), [team\_folder/create](/dropbox-api/api-reference/business-endpoints/team/team-folder-create), [team\_folder/permanently\_delete](/dropbox-api/api-reference/business-endpoints/team/team-folder-permanently-delete), or [team\_folder/rename](/dropbox-api/api-reference/business-endpoints/team/team-folder-rename) endpoints for a team with `has_team_shared_dropbox: true` will fail with either a `team_shared_dropbox_error/disallowed` or `invalid_account_type/feature` error. Calling [team\_folder/get\_info](/dropbox-api/api-reference/business-endpoints/team/team-folder-get-info) and [team\_folder/list](/dropbox-api/api-reference/business-endpoints/team/team-folder-list) for a team with `has_team_shared_dropbox: true` will only return information about the team space.

For team-linked apps that need to access the team space, you’ll need both `Dropbox-API-Path-Root` and `Dropbox-API-Select-Admin` headers. If you don’t specify the `Dropbox-API-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 under the team space for a team with `has_team_shared_dropbox: true` you can use the [/sharing/share\_folder](/dropbox-api/api-reference/user-endpoints/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 the team space configuration?
  * When a team is migrated from team folders tothe team space configuration, 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](https://help.dropbox.com/plans/upcoming-business-team-changes).
* When happens if an app isn’t updated to support accessing the team space and a team is migrated to use the team space configuration?
  * 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. Team members receive a new namespace ID for their root namespace.
* 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](https://help.dropbox.com/organize/identify-team-space-experience) 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 the user has access to, use [/files/list\_folder](/dropbox-api/api-reference/user-endpoints/files/list-folder) with the `Dropbox-API-Path-Root` header set to account’s root namespace ID as root and set the path to `""`. Refer to the “Using the Dropbox-API-Path-Root Header” section above for more information.

## Additional Resources

* \[Developer Blog Post] [Manage team sharing in your Dropbox app](https://dropbox.tech/developers/manage-team-sharing-in-your-dropbox-app)
* \[Developer Blog Post] [Implement restrictive access using the Dropbox API](https://dropbox.tech/developers/implementing-restricted-access-with-nested-permissions-and-folders)
* \[Developer Guide] [Team Administration Guide](/dropbox-api/docs/team-administration)