> ## 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.

# Box

# Set Up the Box Connector

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

* **Airia-managed OAuth** — Use Airia's built-in Box application. No Box Developer Console setup is required.
* **Bring Your Own OAuth (BYOO)** — Register your organization's own Box 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 Box Data Source](#create-a-box-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 Box 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 Box Data Source](#create-a-box-data-source).

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

### 1. Get the Redirect URL from Airia

Before creating the app in Box, 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 **Box**.
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 Box Developer Console exactly as shown. A mismatch causes a `redirect_uri_mismatch` error during authentication.

### 2. Create a Box App

1. Go to the [Box Developer Console](https://app.box.com/developers/console) and create a new app.
2. Select **Custom App**.
3. For the authentication method, select **User Authentication (OAuth 2.0)**.
4. Enter a name for the app (e.g., `Airia Connector`) and create it.

### 3. Configure the App

1. Open the app's **Configuration** tab.
2. Under **OAuth 2.0 Redirect URIs**, paste the Redirect URL you copied from Airia in Step 1.
3. Under **Application Scopes**, enable:
   * **Read and write all files and folders stored in Box** (`root_readwrite`)
   * **Manage webhooks** (`manage_webhook`)
4. Save the changes.
5. Under **OAuth 2.0 Credentials**, copy the **Client ID** and **Client Secret** — you will need these in the next section.

> 💡 Note: Depending on your Box enterprise settings, a Box admin may need to authorize the app before users can grant it access. Check **Apps** in the Box Admin Console if authentication is blocked.

## Register the OAuth Connector in Airia

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

## Create a Box Data Source

### 1. Add a New Box Data Source

1. In the Airia platform, navigate to **Available data sources**.
2. Select the **Box** 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 Box OAuth connector you registered above (BYOO).
2. For **Credentials**, choose `Create new credential`, or select an existing Box 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 Box with an account that has access to the content you want to ingest, and grant 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 within it, 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. The original Box folder structure is preserved and displayed within the data source.

## OAuth Scopes

| Scope            | Purpose                                                                                       |
| ---------------- | --------------------------------------------------------------------------------------------- |
| `root_readwrite` | Box's content scope — lets Airia browse folders and read the content of the files you select. |
| `manage_webhook` | Lets Airia manage webhooks used to detect content changes in Box.                             |

## Migrate Existing Data Sources from the Legacy Authentication Flow

Box data sources created with the legacy authentication flow (signing in to Box 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 Box 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 `redirect_uri_mismatch`       | The redirect URI in the Box Developer Console does not match Airia's | Copy the exact Redirect URL from the Airia Box connector form and paste it into the Box Developer Console.                                                                |
| Users cannot grant access to the app                    | The Box enterprise requires admin authorization for custom apps      | Ask a Box admin to authorize the app in the Box Admin Console.                                                                                                            |
| Authentication succeeds but browsing or ingestion fails | The Box app is missing a required application scope                  | Enable the missing scope in the Box Developer Console **Configuration** tab, add it to the connector's scopes in Airia, then create a new credential and re-authenticate. |
| 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 Box data source is ready to be used with an Agent.