Skip to main content

​
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 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.
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 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).
  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

​
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

​
Troubleshooting

​
Next Steps

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