• Sign in

Dropbox for Business API

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

App permission types

There are four different types of Dropbox for 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 for Business app, visit the Dropbox for Business app creation page.

Linking to a team

Developers will need to direct a Dropbox for Business team administrator through the standard OAuth 2.0 flow to install their application on a Dropbox for 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 for 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 for Business API application was created by a user that is an admin on your test Dropbox for 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 for 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. Two additional errors may occur when using X-Dropbox-Perform-As-Team-Member:

  • 403 Member ID doesn't exist on the team.
  • 403 Member is in the "invited" state, which is not supported at this time.

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 for Business team. When you are ready to exit development and deploy your app more broadly, you will need to apply for Production status.

Rate limit

Dropbox for 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 for Business API rate limit, we will return a 429 status code with a Retry-After header.

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

Webhooks

Dropbox for 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",
        ...
      ]
    },
    ...
  ]
}