Dropbox Connection

Connect to Dropbox to manage files and folders from your workflows.

Configuration

Field	Description	Required
Access Token	Short-lived OAuth2 access token (≈4 hours). Leave blank if you provide a refresh token.	Optional
Refresh Token	Long-lived OAuth2 refresh token. Recommended for production — used to automatically mint a fresh access token on every workflow run.	Optional
App Key	Your Dropbox app's key (from the App Console). Required when using a refresh token.	Optional
App Secret	Your Dropbox app's secret. Required when using a refresh token.	Optional

You must provide either an access token or the trio of refresh token + app key + app secret.

Recommended: Refresh Token (long-lived)

Short-lived access tokens expire after ~4 hours, which breaks scheduled workflows. The refresh-token flow keeps the connection alive indefinitely.

One-time setup

1. Go to the Dropbox App Console and either create an app (Scoped access + Full Dropbox or App folder) or open your existing one.

2. Under Permissions, enable the scopes your workflows need (e.g., files.metadata.read, files.content.read, files.content.write).

3. Open the Settings tab and copy the App key and App secret.

4. Build the authorization URL — replace <APP_KEY> with your app key:

   https://www.dropbox.com/oauth2/authorize?client_id=<APP_KEY>&response_type=code&token_access_type=offline

   The token_access_type=offline parameter is what makes Dropbox return a refresh token.

5. Open the URL in a browser, sign in, and click Allow. Dropbox shows you an authorization code — copy it.

6. Exchange the code for tokens. Run this curl from any terminal, replacing the placeholders:

   curl https://api.dropbox.com/oauth2/token \
     -d code=<AUTH_CODE> \
     -d grant_type=authorization_code \
     -u <APP_KEY>:<APP_SECRET>

   The response contains:

   {
     "access_token": "sl.B...",
     "refresh_token": "rt-...",
     "expires_in": 14400
   }

7. Save refresh_token, app_key, and app_secret into the connection's fields. Leave Access Token blank — a fresh one is minted on every workflow run.

Quick option: Generated access token (development only)

For one-off testing you can generate a token without going through OAuth:

1. Open your app in the Dropbox App Console.
2. On the Settings tab, scroll to Generated access token and click Generate.
3. Paste it into the Access Token field.

WARNING

Generated tokens expire in ~4 hours. Workflows scheduled after that window will fail. Use the refresh-token setup above for anything beyond a quick test.

Usage

Once created, this connection becomes available in:

• Dropbox — list, upload, download, delete, copy, move, search, and create folders

Webhook URL (for the Dropbox Trigger)

When the connection is created the system generates a stable webhook token. The URL has the form:

https://<your-deployment>/api/conn-webhook/<connection-webhook-token>

Fetch the token from the connection's metadata:

curl -H "Authorization: Bearer $TOKEN" \
  https://<your-deployment>/api/connections/<connection-id> \
  | jq '.data.metadata.webhook_token'

Paste the full URL into the Dropbox App Console → Webhooks tab → Webhook URIs. Dropbox does not expose an API to register webhook URIs; the App Console is the only path (see the Dropbox webhook reference). The same URL handles every workflow built on this connection — register once.

The App Secret on the connection is what we use to verify Dropbox's HMAC signature on each delivery. Without it, the trigger refuses to publish.

Webhook URL must be re-pasted on re-seed

Unlike Slack and HubSpot, there is no Dropbox API to update the webhook URL programmatically. Every time you re-seed the database (which regenerates the connection's webhook token), the URL Dropbox knows about becomes stale, and Dropbox deliveries land on a token our backend no longer recognises. You need to copy the new URL out of the connection and paste it back into the Dropbox App Console.

To check whether Dropbox has the current URL on file, compare:

# Our side
curl -H "Authorization: Bearer $TOKEN" \
  https://<your-deployment>/api/connections/<connection-id> \
  | jq '.data.metadata.webhook_token'

…against the URI shown in the Dropbox App Console → Webhooks tab. If they don't match, re-paste.

Testing the Dropbox Trigger

php artisan integrations:test --filter=Dropbox exercises the trigger via observation: the sibling Dropbox action workflow runs first (it creates a folder, copies, and deletes files), Dropbox delivers change notifications to this connection's webhook URL, and the runner picks up the resulting trigger workflow execution. No human action needed.

If the trigger row reports skipped, the most common cause is that the webhook URL in the Dropbox App Console is stale (doesn't match the current connection's token) — re-paste the current URL.

Self-fire & loop hazard

Dropbox webhooks fire on ANY change to the account's files — including changes made via the same connection's action nodes. That means:

• An action workflow that uploads or renames a file via the Dropbox node will fire a change notification back to the Dropbox Trigger workflow on the same connection. Useful for integrations:test self-loops.
• A trigger workflow that filters on change AND modifies files in response → infinite loop.

Mitigations:

• End trigger workflows in non-modifying nodes (a switch with no rules, a datastore write, an email send).
• Or scope your trigger workflow's downstream actions to a path the trigger doesn't watch.