API updates to better support team spaces

Dropbox API Changes for Updated Team Spaces

Dropbox is rolling out significant updates to its team space functionality that aim to improve scalability and privacy. In conjunction, the Dropbox API is gaining new features and behavior changes that developers should account for in their apps by January 31, 2024. The rollout is happening incrementally over the coming months, and affected teams will receive email notification ahead of their scheduled update.

The changes affect apps that interact with team-owned content, particularly those that rely on assumptions about how team spaces are structured. Developers need to detect which features are available on a specific team or user account and adjust their app's behavior accordingly.

Determining Available Features

To identify which capabilities a given team currently supports, apps can query /2/team/features/get_values, which reports the team's feature set as the rollout progresses:

For user-linked apps, equivalent feature information is available via /2/users/features/get_values. Apps should read these values and base their logic on the reported capabilities. For example, an account that reports distinct_member_home: true from /2/users/features/get_values should continue using the Dropbox-API-Path-Root header to access the team space, leveraging the root_info.root_namespace_id value returned by /2/users/get_current_account for that account.

Behavioral Changes with Updated Team Spaces

Teams that have moved to the updated team space configuration will exhibit several differences that developers need to handle:

• Root namespace varies by member. While the root_info.root_namespace_id from /2/users/get_current_account still represents the account's root namespace, it will not necessarily be identical across members of the same team. This is particularly true for teams with has_team_shared_dropbox: false.
• No more single team folder guarantee. Historically, all teams with a team space had has_team_shared_dropbox: true from /2/team/features/get_values and listed exactly one team folder (the team space itself) with is_team_shared_dropbox: true via /2/team/team_folder/list. Going forward, teams with the updated team space will return has_team_shared_dropbox: false and may have multiple team folders listed by /2/team/team_folder/list (and its /continue endpoint), each with is_team_shared_dropbox: false. Therefore, do not use the count of items returned by that endpoint to infer whether a team space is in use. Instead, check features via /2/team/features/get_values and obtain root information from /2/users/get_current_account.
• Root info type changes. Previously, every user with a team space had a root_info of type team from /2/users/get_current_account. Users on the updated configuration will instead have root_info of type user. The root info type no longer indicates whether a team space exists; it only shows whether the team space is shared identically across all members. Use /2/users/features/get_values to inspect user-level features.
• Listing all team content requires more steps. Because each member on an updated team space has their own team member root, a single call to /2/files/list_folder (or its /continue flow) can no longer enumerate the entire team's content. To aggregate all team content, use /2/team/namespaces/list (or its /continue endpoint) to obtain all of the team's namespaces, or /2/team/team_folder/list to list just team folders. Individual namespaces can then be listed with /2/files/list_folder as needed.
• Direct writes to the team space root are blocked. For updated teams, attempting to create files or folders directly at the top level of the team space via the /2/files endpoints will fail. Team-linked apps should use /2/team/team_folder/create to create a team folder within the team space. The /2/files endpoints can only add content within existing team folders or member folders.
• Default sharing behavior changes. On teams with has_team_shared_dropbox: true, newly created folders in the team space are shared with the whole team by default. Newly created team folders on the updated configuration are not shared with anyone by default; apps can share them with relevant groups by calling /2/sharing/add_folder_member. Teams without a team space can still create team folders via /2/team/team_folder/create.
• Metadata reflects folder hierarchy. On updated teams, top-level folders within the team space are treated as actual team folders. Shared folder metadata for these will show is_inside_team_folder: false and is_team_folder: true.

All teams will eventually be moved to the updated configuration, so apps should not assume the legacy behavior. For full details on interacting with team files in the new model, consult Dropbox's updated Team Files Guide.