Skip to content

Setting up Dropbox Integration

This guide explains how to set up the Dropbox integration for DocuElevate.

Required Configuration Parameters

Variable Description
DROPBOX_APP_KEY Dropbox API app key
DROPBOX_APP_SECRET Dropbox API app secret
DROPBOX_REFRESH_TOKEN Optional OAuth2 grant for the system-level connection
DROPBOX_FOLDER Default folder path for Dropbox uploads
DROPBOX_ALLOW_GLOBAL_CREDENTIALS_FOR_INTEGRATIONS Let users authorize against the operator-managed Dropbox app

For a complete list of configuration options, see the Configuration Guide.

Setup Methods

DocuElevate supports two distinct Dropbox OAuth flows:

  1. Per-User Integration Wizard (Recommended for end users): Triggered from the Integrations dashboard (/integrations) by clicking Authorize on a Dropbox destination or Dropbox-backed Watch Folder. Credentials are saved securely to your personal integration record — global settings are never exposed.
  2. System-Level Setup Wizard: Available at /dropbox-setup for administrators configuring the global system-wide Dropbox connection. Generates environment variables for all worker nodes.
  3. Manual Setup: Following the step-by-step instructions in this document.

Per-User OAuth Flow (Integrations Dashboard)

End users authorize their own Dropbox integration from the Integrations dashboard:

  1. Navigate to /integrations and add a Dropbox destination (or a Watch Folder with source_type = dropbox).
  2. Enter the non-secret integration settings and choose Save & connect Dropbox.
  3. If the administrator has configured system-wide Dropbox app credentials (DROPBOX_APP_KEY / DROPBOX_APP_SECRET) and enabled DROPBOX_ALLOW_GLOBAL_CREDENTIALS_FOR_INTEGRATIONS, the wizard uses that app — no need to register a Dropbox app per user.
  4. Authorize access in Dropbox; the refresh token is automatically saved to your personal integration record.
  5. Use the interactive folder browser to navigate through any subpath and select the source or target folder. You can create a new folder in the currently open location and select it immediately; no path memorization is required.
  6. Save the folder selection to return to /integrations. Re-authorization remains available via Re-Authorize.

For an existing archive, enable True up existing corpus on the Dropbox-backed Watch Folder. DocuElevate performs one recursive import of the selected folder and all subfolders, records Dropbox file IDs and revisions, then reuses Dropbox's change cursor for later watch cycles. Watch Folder sources fail closed: source deletion is possible only when preserve_source_files=false and delete_after_process=true. Missing preserve_source_files is treated as protected. The UI defaults to Quelldateien NICHT LÖSCHEN! and shows a prominent red alarm on every source card where deletion is actually enabled.

Note: The renewable user grant is stored encrypted per integration. In shared-app mode, the operator App Key and App Secret remain in operator configuration and are not copied into the user's database record. Workers resolve both parts at execution time, so authorization changes do not require a restart.

Using the System-Level Setup Wizard (Admin)

The easiest way to configure the global Dropbox integration is to use the built-in setup wizard:

  1. Navigate to the /dropbox-setup page in your DocuElevate instance.
  2. Follow the on-screen instructions to create a Dropbox app.
  3. Enter your App Key and App Secret in the wizard.
  4. Optionally specify a custom folder path for uploads.
  5. Click Start Authentication Flow to begin the authorization process.
  6. Complete the Dropbox authentication process.
  7. The system will automatically exchange the authorization code for a refresh token.
  8. Copy the generated environment variables for your worker nodes.

The wizard handles all the token exchange steps and provides you with the exact configuration needed for your environment.

Step-by-Step Manual Setup Instructions

1. Create a Dropbox App

  1. Go to the Dropbox Developer Apps Console
  2. Click "Create app"
  3. Select "Scoped access" for API
  4. Choose "Full Dropbox" access (or "App folder" for more restricted access)
  5. Give your app a name (e.g., "DocuElevate")
  6. Click "Create app"

2. Configure App Permissions

  1. In your app's settings page, go to the "Permissions" tab
  2. Enable the following permissions:
  3. files.content.write (to upload files)
  4. files.content.read (if you need to read file content)
  5. Click "Submit" to save changes

3. Get App Key and Secret

  1. On your app's settings page, find the "App key" and "App secret"
  2. Set these as DROPBOX_APP_KEY and DROPBOX_APP_SECRET in your configuration

4. Generate a Refresh Token

  1. Go to the "OAuth 2" tab in your app settings
  2. Add a redirect URI: http://localhost (this is for the authorization flow)
  3. Generate an authorization URL with these instructions:

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

  1. Replace YOUR_APP_KEY with your app key
  2. Open this URL in your browser
  3. Authorize the app when prompted
  4. You'll be redirected to localhost with a code parameter in the URL
  5. Copy this code parameter

5. Exchange the Code for a Refresh Token

  1. Use this curl command to exchange the code for tokens:

bash curl -X POST https://api.dropboxapi.com/oauth2/token \ -d code=YOUR_AUTH_CODE \ -d grant_type=authorization_code \ -d client_id=YOUR_APP_KEY \ -d client_secret=YOUR_APP_SECRET \ -d redirect_uri=http://localhost

  1. From the response, copy the refresh_token value

6. Configure DocuElevate

  1. Set DROPBOX_APP_KEY, DROPBOX_APP_SECRET, and DROPBOX_REFRESH_TOKEN with your values
  2. Set DROPBOX_FOLDER to the path where files should be uploaded (e.g., /Documents/Uploads)

Token Management

The system will use the refresh token to automatically generate short-lived access tokens when needed. Refresh tokens typically don't expire unless revoked.

Testing Your Token

You can test if your token is working correctly:

  1. Navigate to the /dropbox-setup page in your DocuElevate instance
  2. Click the "Test Token" button to verify your credentials
  3. If the test fails, click "Refresh Token" to obtain a new refresh token

Troubleshooting

If you encounter issues with Dropbox integration:

  1. Authentication Errors: Make sure your App Key and App Secret are correct
  2. Token Expired: Click "Refresh Token" button on the setup page to obtain a new token
  3. Folder Permissions: Ensure your app has the correct permissions enabled for file operations
  4. Invalid Redirect URI: See section below for the most common cause and fix.
  5. Rate Limiting: Dropbox API has rate limits; if exceeded, wait and try again

Fixing "Invalid redirect_uri" Error

This error appears on the Dropbox authorization page when the redirect URI in the OAuth request does not match any URI registered in your Dropbox app console.

Most common cause: The application is deployed behind a reverse proxy (Traefik, Nginx, Caddy) that does not forward the X-Forwarded-Proto: https header to DocuElevate. Without this header, the server cannot determine that it is being accessed over HTTPS and may construct an http:// redirect URI, while the registered URI in Dropbox is https://.

Fix:

Option 1 – Configure your proxy to forward X-Forwarded-Proto:

proxy_set_header X-Forwarded-Proto $scheme;

Option 2 – Set PUBLIC_BASE_URL in your environment (recommended for most deployments):

PUBLIC_BASE_URL=https://docuelevate.example.com

When PUBLIC_BASE_URL is set, DocuElevate uses it directly for all OAuth redirect URIs instead of trying to infer the scheme from request headers. This is the most reliable option.

After setting PUBLIC_BASE_URL, ensure the Dropbox app console redirect URI matches exactly (e.g., https://docuelevate.example.com/dropbox-callback). The setup wizard at /dropbox-setup will show you the exact URI to register.

For more general configuration issues, see the Configuration Troubleshooting Guide.