copilot-swe-agent[bot]
d6c21b8026
Updated DropboxSetup.md, OneDriveSetup.md, and GoogleDriveSetup.md to document the new system credentials toggle and folder browser features. Added API documentation for POST /api/dropbox/list-folders and POST /api/onedrive/list-folders endpoints. Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>
136 lines
6.5 KiB
Markdown
136 lines
6.5 KiB
Markdown
# 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` | OAuth2 refresh token for Dropbox |
|
|
| `DROPBOX_FOLDER` | Default folder path for Dropbox uploads |
|
|
|
|
For a complete list of configuration options, see the [Configuration Guide](ConfigurationGuide.md).
|
|
|
|
## 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 click **+ Add Destination** (or **+ Add Source** for Watch Folder).
|
|
2. Create a Dropbox destination integration (or a Watch Folder with `source_type = dropbox`).
|
|
3. Click the **Authorize** button next to the integration — it links directly to the OAuth wizard pre-loaded with your integration's configuration.
|
|
4. If the administrator has configured system-wide Dropbox app credentials (`DROPBOX_APP_KEY` / `DROPBOX_APP_SECRET`), the wizard defaults to using them — no need to register your own Dropbox app. Uncheck the toggle to use custom credentials if needed.
|
|
5. Click **Start Authentication Flow**, authorize access in Dropbox, and the refresh token is automatically saved to your personal integration record.
|
|
6. After authorization, an interactive **folder browser** lets you select the target folder directly from your Dropbox — no need to manually type folder paths.
|
|
7. The page redirects to `/integrations` on success. Re-authorization is available at any time via the **Re-Authorize** button.
|
|
|
|
> **Note:** Your credentials are stored encrypted per-integration and are never mixed with other users' data. Each user can have multiple Dropbox integrations with independent tokens.
|
|
|
|
## 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](https://www.dropbox.com/developers/apps)
|
|
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:
|
|
- `files.content.write` (to upload files)
|
|
- `files.content.read` (if you need to read file content)
|
|
3. 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
|
|
```
|
|
|
|
4. Replace `YOUR_APP_KEY` with your app key
|
|
5. Open this URL in your browser
|
|
6. Authorize the app when prompted
|
|
7. You'll be redirected to `localhost` with a code parameter in the URL
|
|
8. 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
|
|
```
|
|
|
|
2. 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**: Verify that the redirect URI in your app settings matches the one used in the authentication flow
|
|
5. **Rate Limiting**: Dropbox API has rate limits; if exceeded, wait and try again
|
|
|
|
For more general configuration issues, see the [Configuration Troubleshooting Guide](ConfigurationTroubleshooting.md).
|