Dropbox Platform developer guide

This is your goto reference for building great apps on the Dropbox 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 Dropbox 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 permission (sometimes referred to as access type in the documentation) determines what data your app can access in a user's Dropbox.

Drop-ins

Strictly speaking, this isn't a permission. When you use Drop-ins, 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. Because Drop-ins don't grant your app direct access to a user's Dropbox, using them doesn't require production approval like other permissions do.

File type

The File type permission gives your app access to all files of a specific type (such as text or image files) across a user's entire Dropbox. You can choose any type appearing in the list below.

  • Text files .applescript, .as, .as3, .c, .cc, .clisp, .coffee, .cpp, .cs, .css, .csv, .cxx, .def, .diff, .erl, .fountain, .ft, .h, .hpp, .htm, .html, .hxx, .inc, .ini, .java, .js, .json, .less, .log, .lua, .m, .markdown, .mat, .md, .mdown, .mkdn, .mm, .mustache, .mxml, .patch, .php, .phtml, .pl, .plist, .properties, .py, .rb, .sass, .scss, .sh, .shtml, .sql, .tab, .taskpaper, .tex, .text, .tmpl, .tsv, .txt, .url, .vb, .xhtml, .xml, .yaml, .yml, and files with no extension
  • Documents .csv, .doc, .dochtml, .docm, .docx, .docxml, .dot, .dothtml, .dotm, .dotx, .eps, .fdf, .key, .keynote, .kth, .mpd, .mpp, .mpt, .mpx, .nmbtemplate, .numbers, .odc, .odg, .odp, .ods, .odt, .pages, .pdf, .pdfxml, .pot, .pothtml, .potm, .potx, .ppa, .ppam, .pps, .ppsm, .ppsx, .ppt, .ppthtml, .pptm, .pptx, .pptxml, .prn, .ps, .pwz, .rtf, .tab, .template, .tsv, .txt, .vdx, .vsd, .vss, .vst, .vsx, .vtx, .wbk, .wiz, .wpd, .wps, .xdf, .xdp, .xlam, .xll, .xlr, .xls, .xlsb, .xlsm, .xlsx, .xltm, .xltx, .xps
  • Images .bmp, .cr2, .gif, .ico, .ithmb, .jpeg, .jpg, .nef, .png, .raw, .svg, .tif, .tiff, .wbmp, .webp
  • Videos .3g2, .3gp, .3gpp, .3gpp2, .asf, .avi, .dv, .dvi, .flv, .m2t, .m4v, .mkv, .mov, .mp4, .mpeg, .mpg, .mts, .ogv, .ogx, .rm, .rmvb, .ts, .vob, .webm, .wmv
  • Audio files .aac, .aif, .aifc, .aiff, .au, .flac, .m4a, .m4b, .m4p, .m4r, .mid, .mp3, .oga, .ogg, .opus, .ra, .ram, .spx, .wav, .wma
  • eBooks .acsm, .aeh, .azw, .cb7, .cba, .cbr, .cbt, .cbz, .ceb, .chm, .epub, .fb2, .ibooks, .kf8, .lit, .lrf, .lrx, .mobi, .opf, .oxps, .pdf, .pdg, .prc, .tebr, .tr2, .tr3, .xeb, .xps

With File type permission, your app sees a filtered view of a user's Dropbox containing only the files which match your selected type. All other files simply don't appear to your app through the API. That means faster performance because you don't spend time fetching information about files you don't need. Your app can see all the user's folders, and even create new folders, but can't move, copy, delete, or share folders (since they might contain files your app can't see).

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.

Dropbox for Business apps

Apps that are linked to Dropbox for Business team admins have a different set of permissions, described in the Dropbox for Business API documentation.

Production approval

When you first create a Dropbox API app, it is given development status. Your app functions the same as any production status app except that it can only be accessed by up to 100 users. (You can enable this from your app's info page on the App Console by clicking Enable additional users.) Many apps such as 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 app. Your request will then be submitted to us for review. We'll review your app as quickly as possible to make sure it adheres to the above guidelines. Be descriptive! The more info you provide when applying, the faster we'll be able to approve your app.

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 or permission. 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.

Features of great Dropbox Platform apps

This section includes many of the practices that great Dropbox 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 Dropbox 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 Dropbox 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 Dropbox Platform

This section describes the types of apps that are not allowed on the Dropbox 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.

App metrics

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

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