> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dropbox

> Dropbox is a cloud file storage and sharing platform - Serval connects with your own Dropbox app so workflows can browse, search, organize, and share files on demand.

## About Dropbox

Dropbox is a cloud file storage and sharing platform. Serval connects using a bring-your-own-app model: your team creates its own Dropbox app and pastes its App key and App secret into Serval's Connect modal - Serval does not own a shared Dropbox app. Serval requests offline access during authorization, so Dropbox issues a long-lived refresh token alongside the short-lived (roughly 4-hour) access token, and Serval renews the access token for you automatically. After connecting, the installation is named from the connected account: the Dropbox team name if the account belongs to a team, otherwise the display name, then email, then ID.

**Authentication:** Bring-your-own Dropbox app OAuth 2.0 (authorization code), with automatic token refresh.

**Data sync:** On demand only. Workflows call Dropbox when they run; there is no background or scheduled sync, and no prebuilt workflows are installed with this integration.

## What the Dropbox integration enables

| Capability               | Description                                                                                                                                |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Account and usage info   | Look up the connected account, other Dropbox users, and storage usage.                                                                     |
| Browse files and folders | List folder contents (with pagination for large folders) and read file or folder details.                                                  |
| Search                   | Find files and folders with filters for path, file status, filename-only matching, extensions, and categories.                             |
| Manage files and folders | Create folders, and delete, move, or copy files and folders.                                                                               |
| Sharing                  | Generate temporary download links, create shared links with settings, list and revoke shared links, share folders, and add folder members. |
| Generic API access       | One "Dropbox API request" action reaches every supported Dropbox operation, and new operations can be added on request.                    |

Anything defined in the [Dropbox API](https://www.dropbox.com/developers/documentation/http/documentation) can be accessed through Serval.

## Get your credentials

Serval connects through a Scoped access Dropbox app that you own, created in the [Dropbox App Console](https://www.dropbox.com/developers/apps). You need the app's App key and App secret from its Settings tab, plus Serval's redirect URI added to the app. See Dropbox's [OAuth guide](https://developers.dropbox.com/oauth-guide) for background.

<Steps>
  <Step title="Create the app">
    In the Dropbox App Console, click **Create app**. Choose **Scoped access** for the API and **Full Dropbox** for the access type (or **App folder** if you only need access within Apps/\<your-app-name>).
  </Step>

  <Step title="Enable the seven required permissions">
    On the **Permissions** tab, enable all seven scopes Serval requests: account\_info.read, files.metadata.read, files.metadata.write, files.content.read, files.content.write, sharing.read, and sharing.write.
  </Step>

  <Step title="Submit the permission changes">
    Scroll to the bottom of the Permissions tab and click **Submit**. Dropbox requires an explicit submit for permission changes.
  </Step>

  <Step title="Add Serval's redirect URI">
    On the **Settings** tab, under **Redirect URIs**, paste the redirect URI shown in Serval's Connect Dropbox modal (use the modal's Copy button) and click **Add**.
  </Step>

  <Step title="Copy the App key and App secret">
    Copy both values from the Settings tab. You will paste them into Serval's Connect Dropbox modal.
  </Step>
</Steps>

<Warning>
  Dropbox ignores permission toggles until you click **Submit** at the bottom of the Permissions tab. Unsaved scopes cause an invalid\_scope error when you try to connect.
</Warning>

<Note>
  The redirect URI is environment-specific. Always copy it from Serval's Connect modal - never type it by hand or reuse one from another environment.
</Note>

## Connect in Serval

<Steps>
  <Step title="Open the Connect Dropbox modal">
    In Serval, add the **Dropbox** integration to open the **Connect Dropbox** modal. It shows a read-only **Redirect URI** field with a Copy button (the button reads "Copy" and switches to "Copied" for 2 seconds). Its helper text reads: "Add this as a Redirect URI in your Dropbox app's Settings tab." Confirm this exact value is saved in your Dropbox app before continuing.
  </Step>

  <Step title="Enter your App key (required)">
    Paste the App key from your Dropbox app's Settings tab. The field's placeholder is "Enter your Dropbox App key". Leading and trailing spaces are trimmed automatically.
  </Step>

  <Step title="Enter your App secret (required)">
    Paste the App secret from the same Settings tab. The field is password-masked, with placeholder "Enter your Dropbox App secret".
  </Step>

  <Step title="Click Connect to Dropbox">
    The button stays disabled until both fields are filled in, and reads "Connecting..." while Serval starts the authorization. You are sent to Dropbox to approve access, then returned to Serval with the connection ready to use.
  </Step>
</Steps>

<Tip>
  Finish the Dropbox approval within 10 minutes of clicking **Connect to Dropbox**. If the window lapses, just reopen the Connect modal and start again.
</Tip>

<Note>
  There is no in-place credential editing for this integration. If you rotate the App secret in the Dropbox App Console, reconnect the integration and enter the new values.
</Note>

## Verifying the connection

The Dropbox integration has no automated health checks in Serval, so nothing runs after you connect and there is no pass/fail status to look for. To verify the connection:

1. Create or run a simple workflow that reads Dropbox data - for example, one that looks up the connected account or lists a folder's contents.
2. If the workflow returns Dropbox data, the connection works.
3. If it fails with an authentication error, reconnect the integration with the current App key and App secret from your Dropbox app's Settings tab.

<Tip>
  A simple account lookup can succeed even when file access is limited. If basic reads work but workflows cannot see files you expect, check the Dropbox app's access type: an **App folder** app can only reach files inside Apps/\<your-app-name>. Create a **Full Dropbox** app and reconnect to reach the whole account.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="invalid_scope when connecting - permissions not enabled or not submitted">
    Serval requests a fixed set of seven permissions on every connection: account\_info.read, files.metadata.read, files.metadata.write, files.content.read, files.content.write, sharing.read, and sharing.write. If any are missing from your Dropbox app's Permissions tab, Dropbox rejects the connection with an invalid\_scope error. Dropbox also ignores permission toggles until you click **Submit** at the bottom of the Permissions tab - enabling a scope without submitting has no effect.
  </Accordion>

  <Accordion title="Redirect URI mismatch at the Dropbox approval step">
    The redirect URI must be added to your Dropbox app's Redirect URIs (Settings tab) exactly as shown in Serval's Connect modal. The value is environment-specific, so a hand-typed or stale URI causes Dropbox to fail the authorization with a redirect URI mismatch. Use the modal's Copy button and re-add the value if in doubt.
  </Accordion>

  <Accordion title="&#x22;Invalid or expired OAuth state&#x22; or &#x22;OAuth session expired, please try again&#x22;">
    Serval holds your App key and App secret for at most 10 minutes between clicking **Connect to Dropbox** and approving on Dropbox's consent screen. Taking longer produces one of these errors. Reopen the Connect modal and restart the flow - nothing is broken on the Dropbox side.
  </Accordion>

  <Accordion title="Connection starts failing within about 4 hours of rotating the App secret">
    If you regenerate the App secret in the Dropbox App Console, Serval's stored copy becomes stale and token refresh starts failing once the current access token expires (within about 4 hours). There is no credential-edit screen for this integration - reconnect it with the new App secret to fix the connection.
  </Accordion>

  <Accordion title="A Dropbox connection made another way dies after a few hours">
    Dropbox only issues a long-lived refresh token when the connection explicitly asks for offline access, which Serval's generic custom-HTTP connection flow cannot do. Connections made that way get only a roughly 4-hour access token and then stop working. Always connect Dropbox through this native integration, which captures the refresh token and renews access automatically.
  </Accordion>

  <Accordion title="Operations with no inputs still need a body of null">
    Dropbox requires a JSON body on every call, even for operations that take no inputs - the convention is a literal null. The "Dropbox API request" action sends null automatically when no body is provided, so simple lookups like the current-account and storage-usage operations work out of the box. If a workflow sets the body explicitly for one of these operations, set it to null rather than leaving it empty.
  </Accordion>

  <Accordion title="Dropbox team-admin features are not supported">
    Team administration (member management, groups, team reporting) requires a team-scoped Dropbox token. Serval deliberately requests only user-scoped permissions, because adding any team scope would change the token type and break every user-level capability the integration provides. Connect as the user whose files you need to work with.
  </Accordion>

  <Accordion title="Direct file content upload and download are not modeled">
    Serval's outbound allow-list permits both api.dropboxapi.com and content.dropboxapi.com, but the "Dropbox API request" action targets only the standard API host, and the integration models only operations on that host. Bulk file content transfer through the content host is not available - use temporary download links and shared links to move file contents instead.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Dropbox integration.