Extensions Guide

With Extensions, users can launch your application directly from Dropbox from either “Open” or “Share” menu on the file after authorizing your app via OAuth.

When the user clicks on the app from a file, Dropbox will pass along file_id  and require_role parameter to the preconfigured Extensions URI. After the app receives the request, the user will be in the app’s workflow and it is responsible for identifying the user, retrieving the source file from Dropbox, providing an app-specific workflow (such as editing the file), and saving the resulting file back to Dropbox when applicable.

Dropbox Extensions can be added to any new or existing Dropbox app with Full Dropbox access.

1. For new apps, create an app with Full Dropbox Access from App Console. For apps using scopes, you will also need at least files.metadata.read scope. See here for more information about OAuth 2 scopes at Dropbox.
   
   If you already have an existing app with Full Dropbox Access, you can add in a new Extension URI within the app Settings page.
   
   
2. From the Settings page, click on “Add” button in the Extensions section to configure the Extension:

• Extension URI: Where Dropbox redirects the user and passes the file_id and require_role value. For example, if you enter https://www.example.com/dropbox_extensions, Dropbox will send https://www.example.com/dropbox_extensions?file_id={dropbox_file_id})&require_role={work/personal}
  • file_id is unique identifier of the file and corresponds to the fileMetadata.id value. Therefore, it can be used used with the Dropbox API endpoints such as /files/get_metadata. 
  • require_role indicates if the user is authorizing from work for team account or personal for a personal account. This can be used in the case you need to re-authorize and the user has linked their personal and work accounts.
• What is the main purpose of this extension?: Select whether you want the Extension to show under “Open” or “Share” menu of the selected file, depending on your app’s functionality.
  • Opening/Editing files: This will show the Extension under “Open” menu of the selected file
  • Sharing/Sending files: This will show the Extension under “Share” menu of the selected file
• Supported File Types: Enter comma-delimited list of supported file extensions. The Extension will only show in either “Open” or “Share” menu of the file types specified.
• Max File Size (MB): [optional] Set a file size limit. If a user selects your Extension on a file bigger than specified size, they will be redirected the following error:

Visibility: At the time of creation, the Extension will be visible only to your Dropbox account, without having to authorize for testing purposes. Once you have configured the Extension settings and have carried out tests to ensure that the Extension works as you intended, you can return to this field and uncheck the Only me box to enable the Extension for other users. Note that once you make it visible to others and if there are users who have already authorized your app, they will see the Extensions appear in their Dropbox without having to authorize the app again.

1. Authorizing the application via OAuth
   Extensions will not show in “Open” or “Share” menu of the end user until a) you have unchecked the "Only me" box under "Visibility" section of the app and b) the user authorizes the app via OAuth*. Note that the users will need to start the OAuth flow from your website, just like any other Dropbox apps. Upon completing the OAuth flow, the application is granted an access token, which can be used to make calls to Dropbox API, such as /users/get_current_account for user information.
   
   *For some Dropbox for Business teams, Extensions may not show up as the team admin manages this setting. Find more information about managing app integrations and Extensions in our help center.
   
   
2. Kicking off the Extensions workflow in Dropbox
   Once the application is authorized, the user may now take an action with the Extension that shows in either “Open” or “Share” menu of a file. When the user clicks on the app, it will trigger Dropbox to redirect the user to the configured Extension URI and pass along the file_id and require_role parameters to the app.
   Before taking further action, check by calling users/get_current_account to ensure account_type in the response corresponds to require_role, as users may have personal and business accounts linked. Note that account_type response will show business while require_role will show work to indicate that the user is on a Dropbox for Business team account. You may also need to re-authorize at this time and can use the value from require_role in the authorization flow.
   
   
3. Doing work with the file
   Depending on your app’s workflow, you will also need to use different API endpoints with the access token and file_id. For example, you can use /files/download to download the file or get the metadata of the file using /files/get_metadata. Note that if you are using a scoped app, you will need to have appropriate permissions to call specific endpoints. Each endpoint in our documentation shows which scope is needed for that respective call.
   
   You can use our API Explorer to easily test out how these API endpoints will behave.
   
   
4. Saving the file back to Dropbox
   If your app modifies the selected file, we would recommend saving the file back to the user’s Dropbox. There are several ways to save it back to Dropbox:
   1. via /files/upload endpoint.
   2. via /files/save_url endpoint.
   3. via the Saver, a pre-built component that makes it easy for users to select where to save their files from inside a Dropbox-trusted UI experience.

To close the loop on the Extensions flow, we recommend that there is a link for the users to get back to Dropbox from your app as well.

• [Developer blog post] New Sample: Image Flipping Extension
• [Developer blog post] Build your own Dropbox Extensions