Skip to main content

​
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

Anything defined in the Dropbox API can be accessed through Serval. When you use the Search Dropbox Files workflow, maxResults must be a whole number from 1 to 1,000. If you omit it, the limit is 25. Invalid limits stop the workflow before it contacts Dropbox. The workflow returns one page. If hasMore is true, additional matches exist. Narrow your query or folder path to reduce the number of matches.

​
Get your credentials

Serval connects through a Scoped access Dropbox app that you own, created in the Dropbox App Console. 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 for background.
1

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>).
2

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

Submit the permission changes

Scroll to the bottom of the Permissions tab and click Submit. Dropbox requires an explicit submit for permission changes.
4

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

Copy the App key and App secret

Copy both values from the Settings tab. You will paste them into Serval’s Connect Dropbox modal.
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.
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.

​
Connect in Serval

1

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

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

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”.
4

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.
Finish the Dropbox approval within 10 minutes of clicking Connect to Dropbox. If the window lapses, just reopen the Connect modal and start again.
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.

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

​
Gotchas and troubleshooting

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.
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.
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.
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.
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.
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.
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.
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.
Need help? Contact support@serval.com for assistance with your Dropbox integration.