Dropbox

What your agents can doCopy Anchor Link

Agents use your connected Dropbox account to work with files, folders, sharing, and team resources.

• Search for files, list folders, and read file versions, tags, and custom properties
• Download a file to read or summarize it, export Paper docs and Google files, and get previews and thumbnails
• Upload files, including large files in upload sessions, and save a file from a public URL
• Create folders, move, copy, rename, tag, lock, and delete files and folders, and restore an earlier version
• Share files and folders, create shared links, and create file requests
• With a team app, manage members, groups, team folders, legal holds, and devices, and read the team's activity log

The agent's API tool reaches api.dropboxapi.com and the upload and download host content.dropboxapi.com. It sends or receives files up to 16 MB in one call. For a larger upload, the agent uses an upload session and sends the file in parts.

AuthenticationCopy Anchor Link

Dropbox doesn't issue long-lived API keys, so Helios connects through an app that you own. Both methods use a scoped app that you create in the Dropbox App Console. See Integration authentication for how credentials are stored and injected.

Helios doesn't ask for scopes. Dropbox gives the token every scope turned on in the app's Permissions tab, so the app's scopes decide what agents can do. Turning on any team scope links the app to a whole team instead of one account. Use a separate app for each method.

For full access, turn on every scope on the Permissions tab that the method can use:

Through a team app, the account scopes in the first rows apply when an agent acts as a team member.

A connection keeps the scopes that were turned on when it was approved. If you turn on a scope later, open the connection in Helios, click Re-connect, and approve again. Until then, calls that need the new scope fail with missing_scope.

Your own Dropbox OAuth appCopy Anchor Link

Any Dropbox account can create an app in the App Console. Dropbox doesn't allow the word "Dropbox" in an app's name.

1. In the Dropbox App Console, click Create app. Choose Scoped access, then Full Dropbox. Choose App folder instead to keep agents and triggers inside one folder. Some calls, such as tags, file locks, and contacts, don't work in an App folder app.

2. On the app's Permissions tab, turn on every scope marked Both in the table above, then click Submit. Leave every team scope off.

3. On the Settings tab, add this URL under Redirect URIs:

   Copy Text

   https://api.heliosapp.com/integrations/dropbox/oauth_callback

4. In Helios, choose Your own Dropbox OAuth app. Enter the App Key and App Secret from the Settings tab.

5. Save, then approve access in Dropbox.

A new app is in development status. It can link only your own account until you click Enable additional users on the Settings tab. A development app can link up to 500 accounts. Once it links 50, Dropbox gives you two weeks to apply for production status before it stops linking new accounts.

Your own Dropbox team appCopy Anchor Link

You need a Dropbox team plan, and a team admin approves the app. The connection reaches every member's Dropbox, so give it only to workflows you trust with the whole team.

1. In the Dropbox App Console, click Create app. Choose Scoped access, then Full Dropbox.

2. On the app's Permissions tab, turn on every scope in the table above, including team_data.member, then click Submit.

3. On the Settings tab, add this URL under Redirect URIs:

   Copy Text

   https://api.heliosapp.com/integrations/dropbox/oauth_callback

4. In Helios, choose Your own Dropbox team app. Enter the App Key and App Secret from the Settings tab.

5. Save. A team admin then approves access in Dropbox for the team.

A new app is in development status and links only one team. To link more, click Enable additional teams on the app's page in the App Console.

The token belongs to the team, not to the admin who approved it. To work in a member's files, the agent first lists the members with team/members/list_v2, then sends the member's ID in the Dropbox-API-Select-User header. To work in the team space or a team folder, it also sends the Dropbox-API-Path-Root header.

TriggersCopy Anchor Link

Dropbox can start a Workflow when something changes. Dropbox only lets you set webhook URLs in the App Console, so you set it up by hand after you connect. Dropbox sends every change to the URL, so there are no events to choose.

1. In Helios, open the connection and click Manage, or Set up webhook on the connection card. Webhook Setup shows the webhook URL and the secret field. Copy the URL.
2. Don't change the Webhook Secret field. Dropbox signs notifications with your app secret, and Helios puts it in this field when you connect. A different value makes Helios reject the notifications.
3. In the App Console, open your app's Settings tab and add the URL in the Webhooks section. Dropbox checks the URL right away.

To stop events, remove the URL in the App Console. Deleting the connection in Helios doesn't remove it.

• Which connection gets which events: a connection through Your own Dropbox OAuth app gets the file and folder events. A connection through Your own Dropbox team app gets team_member.changed, and needs members.read for it. Helios doesn't read the file changes of a team's members, so the trigger picker shows the file and folder events as unavailable on a team connection. Connect a member's account with Your own Dropbox OAuth app to watch their files.
• New or changed file: Dropbox reports a new file and a changed file the same way. Helios asks Dropbox whether the path had an earlier version. file.created means the path had none, and file.updated means it had one. A file uploaded where a deleted file used to be counts as file.updated. So does a file that was added and then changed again before Helios read the change.
• Moves and deletions: a move or rename shows up as item.deleted at the old path and file.created or folder.created at the new one. Dropbox reports a deleted file and a deleted folder the same way, so item.deleted covers both.
• Team members: Dropbox reports an invite, a join, a removal, and a change to a member's profile or permissions the same way, so team_member.changed covers all of them.
• Path is optional. It matches the item's full path and ignores case. /Invoices/* matches the items directly in Invoices, /Invoices/** matches everything under it, and **/*.pdf matches every PDF.
• The payload of a file or folder event is the item's metadata from Dropbox. Files carry their name, path, ID, size, revision, and modification time, plus previous_rev, the revision before this one at the same path or null. Deletions carry only the name and path. team_member.changed carries the team_id and the member_id that changed.
• In a Dropbox team account, Helios watches the member's own folders, not the team space.

Notifications are verified with the HMAC-SHA256 X-Dropbox-Signature header.

Dropbox disables a webhook that fails more than 35 times in 10 minutes with a failure rate above 4.5%, and emails the app's owner. To turn it back on, open the Webhooks section in the App Console.

Check that it worksCopy Anchor Link

• The connection: after you approve access, the connection's status shows Connected. Error means Dropbox rejected the token. See Common errors.
• The webhook: in the App Console, the URL is listed in the Webhooks section of the app's Settings tab, with the status Enabled.
• A trigger:
  1. Add file.created to a workflow with no filters. On a team connection, use team_member.changed.
  2. Add a file to the connected Dropbox, or invite someone to the team.
  3. Check that a run starts. Then open the connection in Helios and click Webhook events to see the event.

Common errorsCopy Anchor Link

LimitsCopy Anchor Link

Dropbox doesn't publish exact rate limits. A call over a limit fails with 429 and a Retry-After header that says how many seconds to wait. Limits apply to each linked account, to the team for team calls, and to the member for calls made as a member. See the Dropbox performance guide.

Some Dropbox team plans also limit the number of upload calls each month. See the data transport limit.