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

# Box

> Connect Mixpeek to your Box account to sync and process files from Box folders.

> [!NOTE]
>
> This guide explains how to connect your Box storage to Mixpeek, enabling automated ingestion and processing of files from Box folders.

## Prerequisites

* An active Box account (Business or Enterprise plan recommended for CCG auth)
* A Box application created at [developer.box.com](https://developer.box.com)
* Client ID and Client Secret from your Box app

## Authentication Methods

Box supports two authentication methods:

| Method | Best For | Token Expiry |
| - | - | - |
| **OAuth (Developer Token)** | Development and testing | 60 minutes |
| **CCG (Client Credentials Grant)** | Production deployments | Auto-refreshes |

> [!WARNING]
>
> Developer tokens expire after 60 minutes and **cannot be refreshed**. Use CCG authentication for production workloads.

## Configuration Steps

**1. Create a Box Application**

1. Go to [developer.box.com](https://developer.box.com) and sign in
2. Click **My Apps** → **Create New App**
3. Select **Custom App** and choose your authentication method:
   * For testing: **User Authentication (OAuth 2.0)**
   * For production: **Server Authentication (Client Credentials Grant)**
4. Name your app and click **Create App**
5. In the app's **Configuration** tab, note down your **Client ID** and **Client Secret**

**2. Get a Developer Token (OAuth only)**

For quick testing with OAuth:

1. Open your app in the Box Developer Console
2. Go to the **Configuration** tab
3. Scroll down to **Developer Token**
4. Click **Generate Developer Token**
5. Copy the token — it's valid for 60 minutes

> [!WARNING]
>
> Generating a new developer token invalidates the previous one. Store it immediately.

**3. Configure CCG (Production)**

For production use with Client Credentials Grant:

1. In your Box app configuration, select **App Access Only** under **App Access Level**
2. Enable **Generate User Access Tokens** under **Advanced Features** (if needed)
3. In the Box Admin Console, approve the app:
   * Go to **Admin Console** → **Apps** → **Custom Apps Manager**
   * Authorize your CCG app
4. Note your **Enterprise ID** from **Admin Console** → **Enterprise Settings** → **Account Info**

**4. Add Box Connection in Mixpeek**

1. Navigate to **Settings** → **Connections** in Mixpeek Studio
2. Click **Add Connection** and select **Box**
3. Enter your connection details:
   * **Connection Name:** A descriptive name (e.g., "Production Box")
   * **Auth Method:** Choose OAuth or CCG
   * **Client ID:** From your Box app configuration
   * **Client Secret:** From your Box app configuration
   * For OAuth: **Access Token** (developer token)
   * For CCG: **Enterprise ID** (from Box Admin Console)
   * **Folder ID:** Box folder to sync (use `0` for root folder)
4. Click **Test Connection** to verify credentials
5. Click **Create Connection**

## API Configuration

You can also create a Box connection directly via the API:

```python Python theme={null}
from mixpeek import Mixpeek

client = Mixpeek(api_key="your-api-key")

# OAuth (developer token)
connection = client.organizations.connections.create(
    name="My Box Storage",
    provider_type="box",
    provider_config={
        "provider_type": "box",
        "credentials": {
            "type": "oauth",
            "client_id": "your-client-id",
            "client_secret": "your-client-secret",
            "access_token": "your-developer-token"
        },
        "folder_id": "0"  # Root folder
    }
)

# CCG (production)
connection = client.organizations.connections.create(
    name="My Box Storage (CCG)",
    provider_type="box",
    provider_config={
        "provider_type": "box",
        "credentials": {
            "type": "ccg",
            "client_id": "your-client-id",
            "client_secret": "your-client-secret",
            "enterprise_id": "your-enterprise-id"
        },
        "folder_id": "0"
    }
)
```

```bash cURL theme={null}
# OAuth (developer token)
curl -X POST https://api.mixpeek.com/v1/organizations/connections \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Box Storage",
    "provider_type": "box",
    "provider_config": {
      "provider_type": "box",
      "credentials": {
        "type": "oauth",
        "client_id": "your-client-id",
        "client_secret": "your-client-secret",
        "access_token": "your-developer-token"
      },
      "folder_id": "0"
    }
  }'

# CCG (production)
curl -X POST https://api.mixpeek.com/v1/organizations/connections \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Box Storage (CCG)",
    "provider_type": "box",
    "provider_config": {
      "provider_type": "box",
      "credentials": {
        "type": "ccg",
        "client_id": "your-client-id",
        "client_secret": "your-client-secret",
        "enterprise_id": "your-enterprise-id"
      },
      "folder_id": "0"
    }
  }'
```

## Setting Up a Sync

Once your connection is created, configure a sync to start ingesting files:

```python theme={null}
# Create a bucket sync from Box
sync = client.buckets.syncs.create(
    bucket_id="your-bucket-id",
    connection_id="your-connection-id",
    source_path="/",          # Folder path within Box (relative to folder_id)
    sync_mode="continuous",   # Keep syncing new/changed files (vs initial_only)
)
```

## Finding Your Folder ID

To sync a specific Box folder (instead of root):

1. Open Box and navigate to the folder
2. Look at the URL: `https://app.box.com/folder/123456789`
3. The number at the end is your **Folder ID**

Use `0` for the root folder.

## Supported File Types

Mixpeek processes all file types from Box. Common supported formats include:

| Type | Formats |
| - | - |
| Documents | PDF, DOCX, XLSX, PPTX, TXT |
| Images | PNG, JPEG, GIF, WEBP |
| Video | MP4, MOV, AVI |
| Audio | MP3, WAV, M4A |
| Data | JSON, CSV, XML |

## Troubleshooting

> [accordion] Developer token expired (0 files discovered)
>
> Developer tokens expire after 60 minutes. Generate a new token from the Box Developer Console and update your connection credentials.
>
> For production use, switch to **CCG authentication** to avoid expiry issues.

> [accordion] No files discovered on re-run
>
> In `continuous` sync mode, only new or modified files since the last sync are processed. If you want to re-process all files, delete and recreate the sync configuration to reset the `last_sync_at` timestamp.

> [accordion] Authentication failed with CCG
>
> Ensure your CCG app has been authorized in the Box Admin Console:
>
> 1. Go to **Admin Console** → **Apps** → **Custom Apps Manager**
> 2. Find your app and click **Authorize**
>
> Also verify that the **Enterprise ID** matches your Box enterprise account.

> [accordion] Access denied to specific folders
>
> For OAuth connections, the developer token grants access based on the Box user's permissions. Ensure the user has access to the target folder.
>
> For CCG connections, the app acts as a service account. Use the Box Admin Console to grant the app access to specific folders if needed.

## Related

* [S3 Integration](https://docs.mixpeek.com/docs/integrations/object-storage/s3.md)
* [S3 Integration](https://docs.mixpeek.com/docs/integrations/object-storage/s3.md)
* [Bucket Syncs](https://docs.mixpeek.com/docs/ingestion/buckets.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.