> ## Documentation Index
> Fetch the complete documentation index at: https://explore.airia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DropBox

# Set Up the Dropbox Connector

The Dropbox Connector allows you to ingest files and folders from your Dropbox storage space directly into your Airia project. You can authenticate in one of two ways:

* **Airia-managed OAuth** — Use Airia's built-in Dropbox application. No Dropbox App Console setup is required.
* **Bring Your Own OAuth (BYOO)** — Register your organization's own Dropbox OAuth application. This gives you full control over the consent screen and the permissions requested.

> 💡 Tip: To use **Airia-managed OAuth**, skip ahead to [Create a Dropbox Data Source](#create-a-dropbox-data-source) and select the **Airia Managed OAuth Connector** when configuring the data source. To use **BYOO**, complete the OAuth app setup below first.

## Set Up Your Dropbox OAuth App

> 💡 Note: This section applies only if you are using **Bring Your Own OAuth**. If you are using **Airia-managed OAuth**, skip to [Create a Dropbox Data Source](#create-a-dropbox-data-source).

This one-time setup registers your organization's OAuth application in the Dropbox App Console so Airia can access Dropbox on your users' behalf.

### 1. Get the Redirect URL from Airia

Before creating the app in Dropbox, copy the redirect URL that Airia will use for the OAuth callback:

1. In the Airia platform, navigate to **Settings** > **Ecosystem** > **App connections**.
2. Select the **Available** tab and click **Dropbox**.
3. Copy the **Redirect URL** displayed on the form (for example, `https://auth.airia.ai/OAuth/callback`).

> ⚠️ Warning: The redirect URL must be pasted into the Dropbox App Console exactly as shown. A mismatch causes a redirect error during authentication.

### 2. Create a Dropbox App

1. Go to the [Dropbox App Console](https://www.dropbox.com/developers/apps) and click **Create app**.
2. Under **Choose an API**, select **Scoped access**.
3. Under **Choose the type of access you need**, select **Full Dropbox**. This allows users to browse and select any folder they have access to. (The **App folder** option restricts access to a single dedicated folder and is not suitable for ingesting existing content.)
4. Enter a name for the app (e.g., `Airia Connector`) and click **Create app**.

### 3. Configure Permissions (Scopes)

1. On your app's page, open the **Permissions** tab.
2. Enable the following scopes:
   * `account_info.read`
   * `files.metadata.read`
   * `files.content.read`
   * `sharing.write`
3. Click **Submit** to save the permissions.

> ⚠️ Warning: Save the permissions **before** users authenticate. Dropbox fixes the scopes on an access token at authorization time — users who authenticated earlier must re-authenticate to pick up newly added scopes.

### 4. Add the Redirect URI and Get Your Credentials

1. Open the **Settings** tab of your Dropbox app.
2. Under **OAuth 2** > **Redirect URIs**, paste the Redirect URL you copied from Airia in Step 1 and click **Add**.
3. Copy the **App key** (your Client ID) and the **App secret** (your Client Secret) — you will need these in the next section.

## Register the OAuth Connector in Airia

1. In the Airia platform, navigate to **Settings** > **Ecosystem** > **App connections**.
2. Select the **Available** tab and click **Dropbox**.
3. Enter the following details:
   * **Name**: A descriptive name to identify this connector (e.g., `Company Dropbox`).
   * **Client ID**: The App key from the Dropbox App Console.
   * **Client Secret**: The App secret from the Dropbox App Console.
   * **Scopes**: Add the scopes configured in the Dropbox App Console (see [OAuth Scopes](#oauth-scopes)).
4. Click **Create**.

## Create a Dropbox Data Source

### 1. Add a New Dropbox Data Source

1. In the Airia platform, navigate to **Available data sources**.
2. Select the **Dropbox** card.

### 2. Configure Data Source Details

1. Provide the following details:
   * **Name**: A mandatory, descriptive name for your data source.
   * **Description**: (Optional) A brief description.
   * **Scope**: Select the Airia project for this data source.
   * **OAuth connector**: From the dropdown, select the **Airia Managed OAuth Connector**, or the Dropbox OAuth connector you registered above (BYOO).
2. For **Credentials**, choose `Create new credential`, or select an existing Dropbox credential.
3. Enter a **Name** for the new credential.
4. Confirm the scopes to request for the authenticating user. The scopes required by the connector are preselected.
5. Click **Authenticate**. Complete the OAuth flow by signing in to Dropbox (or with a linked Google or Apple account) using an account that has access to the content you want to ingest, and allow the requested access.

### 3. Select Content and Start Ingestion

1. After you authenticate, click **Select Content** to open the file picker.
2. Browse and select the folders and files you want to ingest. You can select and deselect individual items.
3. Confirm your selection and save the data source to start ingestion.

> 💡 Tip: Selecting a folder will sync everything underneath that folder, including files, subfolders, and their content. Only supported file types will be synced. Reprocessing the data source will automatically sync newly added content, update modified content, and delete removed items within the selected folder.

> 💡 Note: To edit your content selection, go to the data source and click **Edit**, then click **Select Content** to make your new selections. You may need to reauthenticate. If you reauthenticate with different user credentials, the file picker will not show previous selections, and you will need to reselect all desired items.

### 4. Monitor Ingestion Status

Once you save the data source, the page refreshes to display the ingestion status. You can view the current status at any time by opening the data source; you can easily browse ingested folders and files within the data source view.

## OAuth Scopes

| Scope                 | Purpose                                                                           |
| --------------------- | --------------------------------------------------------------------------------- |
| `account_info.read`   | Identify the Dropbox account that authenticated.                                  |
| `files.metadata.read` | List folders and files so you can browse and select content.                      |
| `files.content.read`  | Download the content of the selected files for ingestion.                         |
| `sharing.write`       | Create shared links so ingested files can be previewed and opened from citations. |

## Migrate Existing Data Sources from the Legacy Authentication Flow

Dropbox data sources created with the legacy authentication flow (signing in to Dropbox directly, without an OAuth connector) should be updated to the connector-based flow. An administrator updates each existing data source once:

1. Open the data source and click **Edit**.
2. Select the **OAuth connector** — your BYOO Dropbox connector, or the Airia Managed OAuth Connector.
3. **Create** a new credential, or **select** an existing one.
4. Complete the OAuth flow to authenticate, then verify your content selection and save.

## Limitations

| Limitation                                  | Details                                                                                                             |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Credentials are user-specific**           | Credentials are not shared. Each user must authenticate independently through the OAuth flow.                       |
| **Scope changes require re-authentication** | Scopes are granted at authorization time. To pick up new scopes, create a new credential and re-authenticate.       |
| **Selection resets on connector change**    | Changing the OAuth connector on a data source resets the credential, and the content selection must be reconfirmed. |

## Troubleshooting

| Symptom                                                    | Likely Cause                                                       | Resolution                                                                                                                                                            |
| ---------------------------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| OAuth callback fails with a redirect error                 | The redirect URI in the Dropbox App Console does not match Airia's | Copy the exact Redirect URL from the Airia Dropbox connector form and paste it into the Dropbox App Console.                                                          |
| Authentication succeeds but browsing or ingestion fails    | The Dropbox app is missing one of the required scopes              | Enable the missing scope in the Dropbox App Console **Permissions** tab, add it to the connector's scopes in Airia, then create a new credential and re-authenticate. |
| A required scope is not offered during credential creation | The scope is not in the OAuth connector's supported scopes         | Edit the connector under **Settings** > **Ecosystem** > **App connections** and add the missing scope.                                                                |
| Selection cleared after changing the connector             | Changing the connector resets the stale credential and selection   | Reauthenticate with the new connector and reselect your folders and files.                                                                                            |

## Next Steps

After your data has been successfully ingested, the Dropbox data source is ready to be used with an Agent.