Warning: API v1 has been deprecated. Learn more.

Dropbox Business API

The Dropbox Business API allows apps to manage the user lifecycle for a Dropbox Business account and perform Core API actions on all members of a team. It gives apps programmatic access to Dropbox Business admin functionality, specifically the Dropbox Business audit log and team usage statistics.

App permission types

There are four different types of Dropbox Business API permissions, with varying level of access to team and user data. You should only request access to the minimum set of permissions that your app requires:

  • Team information – Information about the team and aggregate usage data
  • Team auditing – Team information, plus the team's detailed activity log
  • Team member file access – Team information and auditing, plus the ability to perform any action as any team member
  • Team member management – Team information, plus the ability to add, edit, and delete team members

Creating an application

To create a Dropbox Business app, visit the Dropbox Business app creation page.

Linking to a team

Developers will need to direct a Dropbox Business team administrator through the standard OAuth 2.0 flow to install their application on a Dropbox Business team. The OAuth response/redirect will include an additional team_id field that can be used to uniquely identify a team.

As with the Core API, once you have a valid token for a team, you can call any method by attaching the following header:

Authorization: Bearer <access token>

Dropbox Business API OAuth tokens can enable extensive access to team data, so it is your responsibility to properly secure them server-side. They should never be cached in insecure environments or downloaded to client devices.

For development testing, if your Dropbox Business API application was created by a user that is an admin on your test Dropbox Business team, you can create a valid token with the "Generate" button under the "Generated Access Token" section of your app in the Dropbox App Console.

Member file access

Make calls to the Dropbox Core API for any member of the Dropbox Business team. Your app must have Team member file access permission.

To make calls on a member's behalf, use the OAuth token granted to the app by the team. Specify the member_id of the user that the app wants to act on using a custom HTTP header called X-Dropbox-Perform-As-Team-Member.

Notes:

  • This feature is currently limited to only team members in the "active" state.
  • A common use case for Team member file access is scanning through member Dropbox accounts. The recommended approach for this is repeated calls to /delta; this is much more efficient than traversing the folder structure using /metadata.

Refer to the Core API documentation for detailed documentation. An additional error may occur when using X-Dropbox-Perform-As-Team-Member:

  • 401 Member ID doesn't exist on the team.

An alternative and advanced method for Business API apps to access and perform operations on team-owned content is to use the Dropbox-API-Select-Admin HTTP header instead of Dropbox-API-Select-User.

There are a several key differences between the two:

First, both headers specify the member_id of a team member in their values, but for Dropbox-API-Select-Admin this must refer to a team admin rather than an arbitrary member.

Second, Dropbox-API-Select-User allows access to and operations on content that currently exists in the "selected" team member's Dropbox. This includes their private files and folders as well as contents of any shared or team folders they not only have access to but also have added to their Dropbox (i.e. "mounted" in API terms).

In contrast, Dropbox-API-Select-Admin allows access to and operations on any team-owned content. This includes any team member's private files and folders as well as contents of any shared folders owned by a member of the team and team folders. In particular, the team admin being impersonated doesn't have to have the target content in their Dropbox and doesn't have to be in the membership of any shared or team folders the content might reside in.

Therefore Dropbox-API-Select-Admin header is particularly useful for accessing content that might not exist in any team member's Dropbox. An example of this is a shared folder that has been deleted from the Dropbox accounts of all team members that have access to it. Another example is a team folder that has no groups associated with it.

Since traditional logical paths in Dropbox must refer to mounted content, the endpoints that support the Dropbox-API-Select-Admin header accept namespace-relative paths. These take the format of ns:<namespace_id><namespace_path>, where <namespace_id> is the shared_folder_id or team_folder_id of the shared folder or the team folder containing the file or folder, respectively, and <namespace_path> is the logical path to the content relative to its shared folder or team folder container.

For example, let's say your app is trying to retrieve metadata associated with cupcake.png in the shared folder Images with shared_folder_id 123456. Let's imagine Dan, the designer, is a collaborator on Images and has added this shared folder to their Dropbox, mounting it inside top-level folder Design (/Design/Images). The traditional method for an app with team member file access to retrieve metadata for cupcake.png would be to call files/get_metadata while impersonating Dan by his member_id and passing in the logical path /Design/Images/cupcake.png. However, the traditional method would fail if Dan were to remove Images from his Dropbox. Calling files/get_metadata while impersonating a team admin with the Dropbox-API-Select-Admin header, and passing in the namespace-relative path, ns:123456/cupcake.png would circumvent this issue, even if that team admin is not a member of Images.

While a namespace-relative path can be used with the Dropbox-API-Select-User header, the shared or team folder it specifies must be mounted in the Dropbox of the team member "selected" by the header.

Note that not all User API endpoints support the Dropbox-API-Select-Admin header. Here is a list of those that do:

  • files/get_metadata
  • files/list_folder
  • files/list_revisions
  • files/restore
  • files/upload
  • files/upload_session
  • files/copy
  • files/create_folder
  • files/delete
  • files/download
  • files/get_preview
  • files/get_temporary_link
  • files/get_thumbnail
  • files/move

Production status

When first created, an app will be in "development" mode, which means it will only be able to link to a single Dropbox Business team. When you are ready to exit development and deploy your app more broadly, there are a couple of things you need to do. First, we require all Dropbox Business app developers to complete a security review before we will grant them production status. Please contact us to get the process started. Second, you will need to apply for production status.

Rate limit

Dropbox Business API calls have a different rate limit than the Core API. Rate limiting is on a per-app-install basis. Other apps installed on a particular team will not impact your application's rate limit, nor will one team on which your app is installed impact other teams' rate limit for your app.

If your application has exceeded the Dropbox Business API rate limit, we will return a 429 status code with a Retry-After header.

Our expectation is that Dropbox Business API developers should not encounter rate limiting during normal use. If you are regularly encountering the rate limit, please contact us.

Webhooks

Dropbox Business API apps that have specified a webhook URL in the App Console will receive change notifications for the team. There are two classes of change notifications, associated with different permissions.

Team member file access notifications

Apps with the Team member file access permission will receive per-user webhook notifications from all members of the team. The webhook notification contains a list of all member_ids that have changes within their account. This is similar to the Core API webhook behavior.

For Team member file access notifications, your endpoint will receive JSON with the following format:

{
  "delta": {
    "teams": {
      "team_id1": [
        "member_id1",
        "member_id2",
        ...
      ],
      "team_id2": [
        "member_id1",
        "member_id2",
        ...
      ],
      ...
    }
  }
}

Note that a single change to a file in a shared folder will trigger a webhook for each user that the folder is shared with (and will also show up in the /delta entries for each account). You may want to track these occurrences to avoid re-processing the same file multiple times. One possible method would be to track a combination of the (unique) shared folder ID, file path, and rev for a file to identify if it is the same as a previously-processed change. Files outside a shared folder don't have this concern.

Team change notifications

Apps with Team member management or Team member file access permissions will receive webhook notifications for changes to the team membership. This type of notification will be triggered in the following cases:

  • User is invited to team
  • User joins team (transitions from "invited" to "active" status)
  • User is removed from team
  • User's profile or permissions are updated

For Team change notifications, your endpoint will receive JSON with the following format:

{
  "team_events": [
    {
      "event": "member_info_change",
      "team_id": "team_id1",
      "member_ids": [
        "member_id1",
        "member_id2",
        ...
      ]
    },
    ...
  ]
}