DBX Platform developer guide

This is your goto reference for building great apps on the DBX Platform and sailing through the app review process. Be sure to also refer to the developer branding guidelines and terms and conditions as you design your app.

App permissions

When you start building an app on the DBX Platform, you'll need to create a Dropbox app in the App Console. As part of the process, you'll need to choose the right permission for your app. Your app's permissions control which data your app can access in a user's Dropbox.

Scoped access

The DBX Platform uses scopes so developers can specify the level of access that their app has to user and team Dropbox data. Scopes are selected in the Permissions tab of an app's settings page. During the OAuth flow, a user authorizes the app to have that specific level of access.

You can learn more about scopes in the OAuth Guide. If you're migrating from a legacy app, we recommend reading Migrating App Permissions and Access Tokens.

When creating a scoped app, developers need to select the level of content access. The selected scopes control an app's behaviors and actions while the access level controls the content and resources the app can act on. Selecting App folder will grant you scoped access only to your app's dedicated folder while selecting Full Dropbox will grant you scoped access to the user's entire Dropbox.

App folder

A dedicated folder named after your app is created within the Apps folder of a user's Dropbox. Your app gets read and write access to this folder only and users can provide content to your app by moving files into this folder.

Full Dropbox

You get full access to all the files and folders in a user's Dropbox.

Your app should use the least privileged permission it can. When applying for production, we'll review that your app doesn't request an unnecessarily broad permission based on the functionality provided by the app. If your app will require a broader permission based on functionality that is planned but not yet implemented, be sure to mention this in your production request.

Pre-built components

Create an App folder or Full Dropbox app to get your Chooser, Saver, or Embedder up and running. Strictly speaking, the pre-built components don't need permissions. When you use the Chooser, Saver, or Embedder your app only gets specific access granted by the user. In the case of the Chooser, your app will have access to files selected by the user. In the case of the Saver, the user will save files from your app to the location they choose. In the case of Embedder, the user only has access to the embedded content. Because the pre-built components don't grant your app direct access to a user's Dropbox, using them doesn't require production approval like other permissions do.

Extensions

Apps using Extensions must have an access type of Full Dropbox. You can learn more about Extensions in the blog post, Build your own Dropbox Extensions, or the Extensions Guide. If you need help building with Extensions, please post on our developer support forum or submit a ticket for direct support.

Production approval

When you first create a Dropbox API app, it's given development status and can only be connected to your own account. You can enable a limited number of other accounts to also be connected to your app while it's still in development mode from your app's info page on the App Console by clicking Enable additional users.

Your app then functions the same as any production status app except that it can only be linked with up to 500 total Dropbox users. However, once your app links 50 Dropbox users, you will have two weeks to apply for and receive production status approval before your app's ability to link additional Dropbox users will be frozen, regardless of how many users between 0 and 500 your app has linked. For more details, please read the Applying for production status section below.

Many apps such as those for demos, hackathons, staging environments, and internal tools can stay in development status. However, if you'd like to open your app to more users, you'll need to apply for production status.

Applying for production status

If you want to share your app with the world, apply for production status from your app's info page, accessible via the App Console. Before applying for production, make sure your app adheres to the developer branding guidelines and terms and conditions. It will be rejected if it doesn't.

When you apply for production status, you'll be prompted to supply additional information such as how your app uses the API, and to upload an icon for the app. Your request will then be submitted to us for review.

While you may submit your request for production status anytime, it will not be reviewed until your app has linked with at least 50 Dropbox users, indicating that it will likely require production status.

Once your app has linked 50 Dropbox users, you will have two weeks to apply for and receive production status approval, if you haven't already done so. If after two weeks you haven't applied for and received production approval, your app's ability to link additional Dropbox users will be frozen until you submit an application and are approved for production status. Once your production status application has been submitted, your app will be reviewed to ensure it adheres to the above guidelines.

Please note, for apps that have been temporarily frozen, the only way to unfreeze your app is to apply for and receive production status. Simply unlinking all of your users will not unfreeze your app.

When submitting an application, please be descriptive! The more info you provide when applying, the faster we may be able to approve your app once it reaches 50 linked Dropbox users.

Once your app is approved for production status, any number of Dropbox users can link to your app. Keep in mind that once your app has production status, you can't change its name. Make sure you're comfortable with your app's configuration before applying. Remember, your app is required to adhere to the production status requirements even after it has been approved.

Note: As part of the deprecation of API v1, Dropbox will no longer approve for production apps that continue to query API v1 endpoints. Please ensure that your app is only querying API v2 endpoints. Read more about the deprecation of API v1 here.

Exceptions

Some apps may be eligible for production status review before reaching 50 linked Dropbox users. If you feel there's a compelling reason for why your app should be reviewed ahead of time, please provide evidence and a detailed explanation under the Request early review field in the production status application form. Otherwise, your app will be reviewed soon after linking 50 Dropbox users.

Features of great DBX Platform apps

This section includes many of the practices that great DBX Platform apps have in common. For the best possible user experience (and your own sanity), try to apply these to your own app as much as you can.

Have clear branding on your app

Specifically:

  • Follow our developer branding guidelines.
  • Don't imply that your app was endorsed, built by, or in partnership with Dropbox.
  • Do mention that you're using the Dropbox service, though.

This is especially important when your app is similar to one of the official Dropbox clients. To avoid user confusion over who built what, please be extra careful to follow the three points above.

Use the minimum permissions you need

If your app only needs the user to select a single file so you can print/publish/post/share it, use the Chooser. It's the easiest way to integrate with Dropbox and simple for users to use as well. If you only need to access files created by your app, use an App Folder. Requesting Full Dropbox access to pick a file when you could use the Chooser isn't a good use of the permission.

Respect user privacy; have a privacy policy

You need to respect users' privacy when they give you access to their Dropbox. Be sure to include a clear privacy policy that's specific to your app and describes what your app will and won't do with user data.

Integrate Dropbox in both the free and paid versions of your app

We find that users are far more likely to upgrade to paid apps when they've already linked their Dropbox account to a free app. Use Dropbox to get more engaged users and offer Dropbox support in both the free and paid versions of your app.

If you're building a developer tool on top of Dropbox, your developers will need their own Dropbox app keys

While we encourage developers to use our official SDKs and libraries, we know there are a lot of different approaches to building frameworks and APIs. Regardless of how an app makes use of the DBX Platform, we need to know what that app is so we can let users know which apps are accessing their data. For that reason, if you provide software or services that wrap the DBX Platform for other developers to use, those developers must still sign up for their own Dropbox app key.

Use a single app key for each distinct app

If you build multiple apps, use one and exactly one key for each app you make. This makes it much easier for us to debug issues when they arise. That said, if you're just building the same app for different platforms (for example, iOS and Android), you can use the same key.

Apps we don't allow on the DBX Platform

This section describes the types of apps that are not allowed on the DBX Platform. Our goal when we first wrote this list was to prevent you from being surprised or disappointed after putting a lot of passion and effort into a project that we can't approve for general use. It's a terrible conversation for everyone involved. This list isn't exhaustive; any apps that violate either of our developer Branding Guidelines or Terms and Conditions won't be approved.

If you feel like your app is an exception, please contact our developer support team.

Don't build apps that promote IP or copyright infringement

Just don't do it.

Don't copy material from other sites unless you have the right to do so

Dropbox requires that users have the right to store the stuff in their Dropbox. If the purpose of your app is to allow users to download content from other services without having the proper legal rights, we won't be able to approve it.

Don't build file sharing apps

Dropbox doesn't support building publicly searchable file sharing networks on top of Dropbox.

Analytics

The App Console provides details about how your app is using the DBX Platform and APIs.

The analytics feature shows statistics on the number of users and activity of your app. You can use these metrics in combination with your own logging and analytics to help track your app's usage and growth.