> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.dropboxapi.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.dropboxapi.com/_mcp/server.

# Extensions

## Overview

With [Extensions](https://www.dropbox.com/features/extensions), users can launch your application directly from Dropbox from either “Open” or “Share” menu on the file after authorizing your app via [OAuth](/dropbox-api/docs/oauth).

![A demo screenshot of extensions available on a user's file](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/dropbox-api.docs.buildwithfern.com/fa89d82c796bd3e26c5ead71fee11fdd853b5d26e6c65ed5463cec7993f4ab7f/docs/assets/migrated/extensions/65cd51c3ad.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260912%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260912T072628Z&X-Amz-Expires=604800&X-Amz-Signature=be009747e66439ce9fdf0c3ab2481f0ac0da2dfce4fc55dd635559f690d2ee52&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

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.

## Setting up your Extension

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](/dropbox-api/docs/developer-resources/developer-guide) from [App Console](https://www.dropbox.com/developers/apps). For apps using scopes, you will also need at least `files.metadata.read` scope. See [here](/dropbox-api/docs/oauth) 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:

![Screenshot of extenions settings modal in developer console](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/dropbox-api.docs.buildwithfern.com/619356934283e3bd00476ace04bde5135261cc8679c0fdcf10887925cd0f5bd7/docs/assets/migrated/extensions/5b9077b123.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260912%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260912T072628Z&X-Amz-Expires=604800&X-Amz-Signature=c4154d65dfdd5ecea8eb1b21eef23a3e0bfc491f74e2ba1bdd08d33aa975ac2c&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

* **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](/dropbox-api/api-reference/user-endpoints/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](https://help.dropbox.com/accounts-billing/multiple-accounts/connect-personal-work-account).

- **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:

![User error shown when a selected file exceeds max file size](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/dropbox-api.docs.buildwithfern.com/319600dfa682efd6a368fa129d1c8d967d71f3fd02f661323eebb946fbd90bc9/docs/assets/migrated/extensions/f921efeaa7.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260912%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260912T072628Z&X-Amz-Expires=604800&X-Amz-Signature=ebf45d2b3bd48c6df8faec0dd085ba246b1512f00742957d091c0f42d8ffa51e&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

**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.

## Using an Extension

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](/dropbox-api/docs/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](/dropbox-api/api-reference/user-endpoints/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](https://help.dropbox.com/teams-admins/admin/app-integrations).
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](/dropbox-api/api-reference/user-endpoints/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 [/fi](/dropbox-api/api-reference/user-endpoints/files/download)[les/download](/dropbox-api/api-reference/user-endpoints/files/download) to download the file or get the metadata of the file using [/f](/dropbox-api/api-reference/user-endpoints/files/get-metadata)[iles/get\_metadata](/dropbox-api/api-reference/user-endpoints/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](/dropbox-api/api-reference) shows which scope is needed for that respective call.

You can use our [API Explorer](https://dropbox.github.io/dropbox-api-v2-explorer/#files_download) 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](/dropbox-api/api-reference/user-endpoints/files/upload) endpoint.
   2. via [/files/save\_url](/dropbox-api/api-reference/user-endpoints/files/save-url) endpoint.
   3. via the [Saver](/dropbox-api/docs/pre-built-components/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.

## Additional Resources

* \[Developer blog post] [New Sample: Image Flipping Extension](https://dropbox.tech/developers/new-sample--image-flipping-extension)
* \[Developer blog post] [Build your own Dropbox Extensions](https://dropbox.tech/developers/build-your-own-dropbox-extensions)