API updates to better support team spaces

Dropbox is updating the team space functionality to improve the scalability and privacy of the team space model. Accordingly we’re introducing some new features and behaviors to the Dropbox API to make sure that apps can properly support team spaces. If your app interacts with team-owned content, read on for information on how to handle these updates in your app’s code.

We’re rolling out the new team features to new and existing teams over the next few months. Customer teams will get an email notification ahead of their scheduled update date. If necessary, please update your app to support these features and changes by January 31, 2024.

In order to better support updated team spaces, we’ve added some new features to the API that your apps can use:

• There are new distinct_member_home and team_shared_dropbox features available on /2/users/features/get_values that apps can use to determine whether or not the user has a home folder distinct from their root folder, and whether or not the user is part of a team with a shared team root, respectively. 
• There’s a new has_distinct_member_homes feature available on /2/team/features/get_values that apps can use to determine whether or not the members of the team have home folders distinct from their root folders.
• There’s a new team_member_root namespace type returned by /2/team/namespaces/list and /2/team/namespaces/list/continue that apps can use to get the team member roots for members of the team, which applies to teams with the updated team space.
• There’s a new root_folder_id field included on TeamMemberProfile returned by /2/team/members/list_v2 and /2/team/members/list/continue_v2 that apps can use to retrieve the namespace ID of the team member’s root.

We plan to eventually have all teams using the latest feature set. You can use these features as reported by /2/team/features/get_values to determine which features a team currently has:

The equivalent features exist on /2/users/features/get_values for user-linked apps.

Use these feature values in your app’s code to determine which features to use and which behaviors to expect.

For example, for an account with distinct_member_home: true from /2/users/features/get_values, continue to use the Dropbox-API-Path-Root header to access the account’s team space, with the root_info.root_namespace_id value from /2/users/get_current_account for that account.

There are also a number of behavioral differences for teams with updated team spaces to be aware of:

• As before, apps can get the namespace ID of the root namespace for an account from the root_info.root_namespace_id value returned by /2/users/get_current_account. However note that this value will not necessarily be the same for all members of a team, in particular for any teams with has_team_shared_dropbox: false.
• Previously, all teams with a team space had has_team_shared_dropbox: true from /2/team/features/get_values and had only one team folder (being the team space) with is_team_shared_dropbox: true listed by /2/team/team_folder/list. Going forward, teams with the updated team space will have has_team_shared_dropbox: false from /2/team/features/get_values and will have their potentially multiple team folders returned by /2/team/team_folder/list[/continue] with each having is_team_shared_dropbox: false. Accordingly, do not rely on the number of items returned by /2/team/team_folder/list[/continue] to determine if a team uses the team space. Instead, use /2/team/features/get_values to determine the features of a team and /2/users/get_current_account to get the root information for an account.
• All users with a team space previously had a root_info of type team from /2/users/get_current_account. Going forward, users with the updated team space will have root_info of type user. Accordingly, do not rely on the root_info type to determine if a team uses the team space; that only indicates if the team shares the team space across all members. Instead, use /2/users/features/get_values to determine the features of a user account.
• Since each member of a team with the updated team space functionality has their own team member root for accessing the team space, it is not possible to use only /2/files/list_folder[/continue] to list all of the team’s content at once. If your app needs to list all team content for a team, you should use /2/team/namespaces/list[/continue] to get the list of all the team’s namespaces, or you can use /2/team/team_folder/list[/continue] to get the list of just the team folders. You can then use /2/files/list_folder[/continue] to list the contents of any/all such namespaces as needed.
• Files and folders may not be added directly to the root of a team space using the /2/files endpoints, for teams with the updated team space. Attempting to create any files or folders directly in the team space using the /2/files endpoints for those teams will fail. Team-linked apps can instead use /2/team/team_folder/create to create a team folder for the team space. For those teams, the /2/files endpoints can be used to add files and folders only within team folders and member folders.
• For teams with has_team_shared_dropbox: true, newly created folders in the team space are shared with the entire team by default. For teams with updated team spaces, newly created team folders are not shared with anyone by default. Apps can share them with appropriate groups by calling /2/sharing/add_folder_member. For teams without a team space, apps can still call /2/team/team_folder/create to create a team folder.
• For teams with the updated team space, top-level folders in the team space are team folders, with values in SharedFolderMetadata objects reflecting this accordingly with "is_inside_team_folder": false and "is_team_folder": true.