DBX Team Administration Guide

Dropbox Business brings the power of Dropbox to organizations. It gives you a central place to manage your company's Dropbox environment, called the admin console. In the Admin Console, admins can manage users, groups, security, content, devices, policies and much more.

Teams are always looking for ways to automate processes to save time and standardize procedures, to enhance consistency and lower maintenance costs. Take, for example, when HR departments need to onboard new employees. Wouldn't things be easier if the new employee automatically received access to Dropbox, with a folder in it with all the documentation they need to read and sign? All without manual work from an IT administrator?

All of this can be accomplished with the Dropbox Business API. This document aims at the most important aspects and best practices to manage your Dropbox team using the Dropbox Business API. An app that uses these endpoints will need to be authorized by a team administrator.  See the OAuth Guide for more information on permissions and scopes to use these endpoints.

The ability to manage users is a powerful function of the Dropbox API, used by many access management and user provisioning applications, and integrations with other systems. Let's review a few key concepts involved. 

Team Roles

In a Dropbox team, users can be either members or administrators. In certain Dropbox Business licenses you have tiered admin permissions. You can have team admins, user management admins and support admins. This Help Center article describes the differences between these roles. 

User Status

When managing users it is important to understand the concept of user status. Some API calls only work on users with certain statuses. There are five possible statuses in a user lifecycle in Dropbox team:

• Invited: User that has been invited to join the team but hasn't accepted the invitation; Invitations are sent over email
• Active: User that has accepted the invitation and joined the team
• Suspended: User that has been suspended by an administrator
• Deleted: User that has been deleted by an administrator. User loses access to Dropbox, their data is either deleted or transferred to another user.
• Disconnected: User that has been removed from the team but not deleted; Instead they were converted to a basic user account. They keep their personal data and lose access to team content.

In Dropbox Business, teams have a license limit. Adding members will consume a license, and removing will free it. To see available & consumed licenses, use the /team/get_info endpoint. Note that active, invited and suspended users count as provisioned. 

List Users

In order to list the users on a team, you use the endpoints /team/members/list and /team/members/list/continue. The include_removed parameter will return the members in all states.

For each member, the list will show a JSON construct similar to this:

A few important fields to mention:

• team_member_id - Unique ID that represents a user that is associated with a team. This is different than the account_id that every Dropbox user has. You can refer to a unique user in business endpoints using either their team_member_id or their account_id.
• external_id - Optional field used to associate this member with an external directory. 
• status - Tells you what state the user is in. They can be active, suspended, removed or invited. 
• role - Member or admin (team admin, user management admin or support admin)
• is_recoverable - When a user is deleted there is a period of time that it is possible to recover it ("is_recoverable": "true"). There are a few reasons why a removed user can't be recovered. Please refer to the documentation. When a user is recoverable, you have 7 days to restore them using the endpoint /team/members/recover.
• is_disconnected - User downgraded to a basic account ("is_disconnected": "true").

Creating Users

When creating users you have some useful configurations available. The endpoint is /team/members/add. Use the new_members array to add multiple members at a time.

For each new member you will use the MemberAddArg structure. The only mandatory field is member_email, but it is a best practice to define member_given_name and member_surname. 

If you're integrating Dropbox with other directories and user provisioning tools, you might want to leverage the external_id field. This allows you to control the value of the ID and match it with external databases. Once you set external_id for a user, the Dropbox APIs enforce uniqueness. No two users can have the same external_id.

When you add a member, the default behavior is that they will receive an email with an invitation to join the team. For some situations, such as when your organization is using SSO, it might be preferable to suppress the invitation emails. Since the users already have IDs and passwords, and will not use the normal Dropbox login process, organizations usually prefer send customized emails with instructions on how to get in Dropbox instead of going through the normal invitation flow. This is also referred to as “silent invitations” and can be done by setting "send_welcome_email": false in the parameters for /team/members/add.

Sometimes users don't take action on invitations and stay in the invited state for a while. You might want to send or resend welcome emails to pending users with the /team/members/send_welcome_email endpoint.

Silent invitations are also useful when you need to set up the Dropbox environment (group membership, team folders and permissions) before users get in. You can use the API to invite the users (without sending emails), create groups, add members to groups, create team folders, give permissions to those groups, and only then send the welcome email. Refer to the Team Files guide for more information on these actions. 

Removing Users

When removing a user with the /team/members/remove endpoint, you need to define what to do with the user's data. You can:

• Transfer their data to another user: use this when other people will be performing that individual's functions and their personal files can be useful
• Keep their data unassigned and transfer it to another user at a later time: this is useful for when you still haven't had the time to evaluate what needs to be kept or a backfill was not defined yet.
• Delete all data from the devices that are connected to their account (use the wipe_data parameter)
• Downgrade the user to a basic account. In this case you can allow that the converted user keeps access to shared folders. This is useful for when you're working with contractors. You can remove them from the team but still collaborate with them. This is an irreversible operation, if the user needs to be back in the team you'll need to re-add them.

Transferring Data

When you choose to transfer the user's data at this point, you need to specify two parameters: transfer_dest_id, the user that will receive the files and transfer_admin_id, the administrator that will receive emails if errors occur. 

If you don't transfer the user's data when removing the user, you can later use the endpoint /team/member/move_former_member_files for that. The files will be available for transfer as long as deleted files are available for the team account. For more information visit the documentation on version history.

Suspending Users

When you just want to remove the user access temporarily, you can suspend the user instead of deleting them by calling /team/members/suspend.

While suspending, you can choose whether to wipe the data out of the devices the user had connected to their Dropbox account. 

Users can be in the suspended state indefinitely, but they will always occupy a user license.

When a user is suspended, their access tokens stop working as well. If they try to call an endpoint using the API while suspended, they will get a 401 Unauthorized error message saying the user is suspended. For more info on this error please visit the Error Handling Guide.

Suspended users can be reinstated, or unsuspended using /team/members/unsuspend.

Creating Groups

Groups are essential to proper content access management. It is not practical to manage individual permissions in folders and files. And with groups it is a lot easier for your users and applications to leverage Dropbox’s sharing capabilities. For more information on using the Dropbox API to manage content sharing, refer to the Sharing Guide and the Team Files Guide.

When creating a group with /team/groups/create you need to specify a group_name. First you need to create an empty group, then add users in subsequent calls.

Some parameters you might find useful:

group_external_id - as with members, in many Dropbox Business deployments, companies leverage a corporate directory and manage group membership outside of Dropbox. This parameter is optional and works as a link between the Dropbox and external directory group entities

group_management_type - defines who can add/remove users from the group. In some cases you'll want the business users to manage their group membership, in others you might want to restrict that control to only the Dropbox administrators.

Adding Users to Groups

Use the /team/groups/members/add endpoint to add users to groups, with the following parameters:

• group (you have to have previously created it)
• a list of members
• set return_members to True if you want to see the list of members in the response. 

The granting of group-owned resources may take additional time. If that's the case, the response will contain the async_job_id. Use the /groups/job_status/get endpoint to determine whether this process has completed. For more information visit the Conventions guide.

Removing Users from Groups

Removing users from groups is analogous to adding them. The endpoint is /team/groups/members/remove. Similarly you need to specify the group, a list of users, and set return_members to true if you want to see the members of the group after the call in the response.

While your application may manage team membership, admins may also manage users through the Dropbox Admin Console(or other apps).

To detect changes to the team in near real-time, your application may use webhooks or the event log. The Detecting Changes Guide describes these methodologies in more detail.

The Dropbox Business API also allows access to additional administration features such as:

Secondary Emails (/team/member/secondary_emails)

• In many organizations users have secondary emails. Dropbox Business allows customers to configure them, and the API has endpoints for that. A good use-case for these endpoints would be a merger or acquisition. No need to disrupt the Dropbox usage, just use the API to add the new email addresses.
  

Member Space Limits (/team/member_space_limits)

• Some teams elect to restrict the amount of space each user has. This can also be done with the API. The Admin Console allows the configuration of a team-wide quota, but if you are looking for custom settings (say for example, per groups of users), you either have to manually edit space limits for each user, or use the API.
  

Managing User Devices and Sessions (/team/devices)

• There are two very useful endpoints to manage connections in your Dropbox team, with very similar names but with distinct functions:
  • /team/devices/list_member_devices - Lists all current sessions for a particular member ID, including the type of client (web, mobile or desktop)
  • /team/devices/list_members_devices - Lists all current sessions for all the members of a team

Legal Holds (/team/legal_holds)

• Legal holds is an add-on feature for Dropbox Business. Team admins are able to view and export all the content that's been created or modified by a particular member. This can be automated with the Dropbox API as well.

Manage linked apps (/team/linked_apps)

As Dropbox's ecosystem expands, team members will link apps to their Dropbox Business account. With these endpoints you can view existing linked apps and revoke their access.