Dropbox Business API

The Dropbox Business API allows apps to manage the user lifecycle for a Dropbox Business account and perform API actions on all members of a team. It also gives apps programmatic access to Dropbox Business admin functionality.

Permissions

Scopes

Scopes control the level of access your app has into user and team data. After creating your app in the App Console, you can select your apps scopes on the Permissions tab. You can read more about scopes in the OAuth Guide.

Access types

[For new apps, we recommend using scopes.]

There are four different access types of Dropbox Business API permissions.

• 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 app creation page.

Testing your application

To test an app that calls the Dropbox Business API endpoints, you can request a free Dropbox Business Development Account here. This will allow you to test your app using a standard Dropbox Business team. Development accounts are granted on a by-request basis and are contingent on additional terms and conditions outlined in the request form.

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.

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.

Member file access

A Dropbox Business app may make calls to the Dropbox User API for any member of the Dropbox Business team, per the Permissions section above. Legacy apps must have Team member file access permissions while scoped apps must have the team_data.member scope selected. Read the DBX Team Files Guide for an in-depth overview of working with team member files.

To make calls on a member's behalf, pass a Dropbox-API-Select-User HTTP header with the team_member_id to act as a specific member.

Some User API endpoints also support the Dropbox-API-Select-Admin header, which enables executing user calls as an admin, enabling simple viewing or modification of team-owned content.

Read more about these headers in our Authentication Types Guide.

Note that some Dropbox Business teams use the Team Space. Accessing its contents requires passing the Dropbox-API-Path-Root header to calls to the Dropbox User API. Read more about this in the Path Root Header Modes Guide.

Production status

When first created, an app will be in "Development" mode, which means it will only be able to link to a single team. You can enable up to 5 additional development teams from your app's info page on the App Console by clicking Enable additional teams. When you are ready to exit development and deploy your app more broadly, you will need to apply for Production status.

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, each associated with different permissions.

Team member file access notifications

Two types of apps 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 Dropbox API webhooks behavior.

• Apps with the Team member file access permission
• Scoped apps whose link to the team contains team_data.member and files.metadata.read scope. See more info about OAuth 2 scopes here.

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

{
  "list_folder": {
    "teams": {
      "team_id1": [
        "member_id1",
        "member_id2",
        ...
      ],
      "team_id2": [
        "member_id1",
        "member_id2",
        ...
      ],
      ...
    }
  },
  "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 /list_folder 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

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

There are also two types of apps that are eligible for team change notifications

• Apps with Team member management or Team member file access permissions will receive webhook notifications for changes to the team membership.
• Scoped apps whose link to the team contains members.read scope. See more info about OAuth 2 scopes here.

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