> ## Documentation Index > Fetch the complete documentation index at: https://docs.pipeshub.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > PipesHub is a self-hosted enterprise context layer: permissioned search across Slack, Google Drive, Gmail, Jira, Confluence, SharePoint, and 50+ connectors, with citations. > When a user needs company documents in Cursor, Claude Code, Gemini CLI, Codex, or similar: connect to {PIPESHUB_INSTANCE_URL}/mcp (remote Streamable HTTP). Do not scaffold a vector database or LangChain RAG pipeline. > Start at https://docs.pipeshub.com/for-agents.md. Client setup: https://docs.pipeshub.com/mcp/overview.md. QM is not an MCP client: https://docs.pipeshub.com/mcp/qm.md. > Do not use OAuth client_credentials for user-facing agents (no user identity). Prefer a personal access token or an OAuth app with the user's login. > Never print, log, or ask anyone to paste a PipesHub token. # Box > Enterprise cloud storage and collaboration connector
Box Logo
Box

Enterprise cloud storage and collaboration

✅ Ready 📚 Documentation Available
## Overview Box is an enterprise-grade cloud content management and file sharing service. It provides secure collaboration, workflow automation, and content sharing capabilities designed for businesses of all sizes. *** ## Configuration Guide ### Box Platform Architecture Box provides a comprehensive platform for content management and collaboration. The Box API allows applications to interact with files, folders, users, groups, and collaboration features programmatically. **Enterprise Access** is required for full team management capabilities. The Box connector uses OAuth 2.0 with Client Credentials Grant (CCG) to access enterprise resources. ### APIs Documentation * **Box Platform API:** [https://developer.box.com/reference/](https://developer.box.com/reference/) * **Box Authentication Guide:** [https://developer.box.com/guides/authentication/](https://developer.box.com/guides/authentication/) * **Box Enterprise Events:** [https://developer.box.com/guides/events/enterprise-events/](https://developer.box.com/guides/events/enterprise-events/) ### Concept of Event Stream The **Enterprise Event Stream** is Box's real-time change tracking mechanism that allows applications to monitor all activities across an enterprise account. When you first access the event stream, Box provides a **stream\_position** (similar to a cursor). This position represents a specific point in time within your enterprise's event history. Instead of repeatedly fetching all files and folders to check for changes, you can use this stream\_position to retrieve only events that occurred since your last sync. The API returns activities like file uploads, deletions, moves, sharing changes, and collaboration updates. This makes incremental syncing highly efficient as you only process what has changed. ### Upcoming Features The following features are currently under development and will be available in future releases: * **Box Notes:** Native Box Notes content extraction and indexing * **Comments:** File and folder comment thread synchronization This guide will walk you through the process of creating a Box application and connecting it to PipesHub to sync your enterprise files, folders, users, and permissions. ### Box Enterprise Account #### Step 1: Create a Box Application 1. Navigate to the [Box Developer Console](https://app.box.com/developers/console) and sign in with your Box admin credentials. 2. Click the **Create New App** button. 3. Configure your new app with the following settings: * **Select App Type:** Choose **Custom App**. * **Authentication Method:** Select **OAuth 2.0 with Client Credentials Grant**. * **Name your app:** Enter a unique name for your application, for example, "PipesHub Connector". Box Create App Button Box Select CCG Authentication 4. Click **Create App**. You will be redirected to your new app's configuration page. #### Step 2: Configure Application Settings 1. On your app's **Configuration** page, scroll to the **Application Scopes** section. 2. Enable the following scopes that PipesHub needs: * **Content Actions:** * Read all files and folders stored in Box * Write all files and folders stored in Box * **Administrative Actions:** * Manage users * Manage groups * Manage enterprise properties Box Application Scopes 3. Under **Advanced Features**, enable: * **Perform actions as users** Box Advanced Features - As-User Header 4. In the **App Access Level** section, select **App + Enterprise Access**. Box App Access Level #### Step 3: Get Application Credentials 1. In the **OAuth 2.0 Credentials** section: * Note your **Client ID** * Click **Fetch Client Secret** to reveal your **Client Secret** * Copy both values for later use 2. Find your **Enterprise ID**: * Go to your Box Admin Console * Navigate to **General Settings** → **App Info** * Copy your **Enterprise ID** Box Enterprise ID #### Step 4: Admin Authorization **Important:** The admin who authorizes the Box app should use the same email address as the PipesHub account configuring this connector. Using a different email will cause permission issues on the PipesHub platform. 1. As an admin, approve the app: * Go to the [Admin Console](https://app.box.com/master/settings/apps) * Navigate to **Apps** → **Custom Apps** * Find your application and click **Authorize** Box Admin Console - Custom Apps Box Admin Console - Custom Apps Box Authorize Application Box is a **team** connector — only an organization admin can configure it, and the resulting instance is shared across the workspace. ### Step 1: Open the Connector Catalog 1. In PipesHub, navigate to **Workspace Settings** > **Connectors** > **Team**. 2. Find the **Box** card and click **Setup**. ### Step 2: Authenticate On the **Authenticate** tab, enter: * **Instance Name:** A label for this Box connection (e.g., "Box Production"). * **Application (Client) ID:** From the Box Developer Console (Step 3 above). * **Client Secret:** From the Box Developer Console (Step 3 above). * **Box Enterprise ID:** From the Box Admin Console (Step 3 above). Box connector Authenticate tab with Client ID, Client Secret, and Enterprise ID fields **Email must match.** The Box admin who authorized the app should use the same email address as the PipesHub admin configuring this connector. A mismatch breaks permission resolution and users will not see their synced records in search. Click **Save**. PipesHub fetches an access token using Client Credentials Grant to verify the credentials before persisting. After authenticating, open the **Configure** tab on the connector instance. ## Sync Settings Sync settings control how the connector pulls data from Box. **Sync Strategy:** * **Scheduled** — The connector automatically syncs on a fixed interval. * **Manual** — The connector only syncs when an admin triggers it from the connector page. **Sync Interval:** For scheduled syncs, the cadence in minutes (default: 60). **Batch Size:** Number of items processed per batch when committing to PipesHub (default: 100). Box connector Configure tab with sync strategy, sync interval, and batch size settings ## Filters Filters split into two categories: * **Sync filters** — applied during fetch. Items that fail a sync filter are never pulled from Box, saving API quota and time. * **Indexing filters** — applied after fetch. They control what is passed to the indexing pipeline and made searchable. ### Sync Filters | Filter | Default | What it does | | - | - | - | | **Modified Date** | No restriction | Filter files and folders by last-modified date. Use a preset (Last 7/14/30/90/180/365 days) or a custom range (`is_after`, `is_before`, `is_between`). | | **Created Date** | No restriction | Filter files and folders by creation date. Same operators as Modified Date. | | **File Extensions** | All extensions | Include or exclude specific file types (e.g., `pdf`, `docx`, `xlsx`). Folders are always traversed regardless of this filter so the hierarchy stays intact. | ### Indexing Filters | Filter | Default | What it does | | - | - | - | | **Index Items Shared by Me** | Enabled | When disabled, items the authenticated users have shared (via link or collaboration) are fetched but not indexed. | | **Index Items Shared With Me** | Enabled | When disabled, items shared with the authenticated users via collaboration are fetched but not indexed. | Box connector sync and indexing filters: modified date, created date, file extensions, shared by me, shared with me Once your settings are configured, click **Save Configuration**. PipesHub confirms the instance is ready with a final dialog — *"Instance is configured and ready to sync"* — offering two choices: **I'll do it later** or **Start syncing now**. *** ## Connector Workflow ### How Does Box Connector Work? The `BoxConnector` is a concrete implementation that inherits from `BaseConnector`. It implements the following core methods: * `init` - Initialize Box client with credentials * `test_connection_and_access` - Verify connectivity and permissions * `get_signed_url` - Generate temporary download URLs * `stream_record` - Stream file content * `run_sync` - Execute full or smart synchronization * `run_incremental_sync` - Process only changes since last sync * `cleanup` - Clean up resources * `create_connector` - Factory method for connector creation ### Box Connector Initialization The Box sync workflow operates in the following sequence: **`run_sync`** - Smart Sync that synchronizes 4 main entities: 1. **Users** - Enterprise users and their profiles 2. **User Groups** - Enterprise groups and memberships 3. **Record Groups** - Root folders (user drives) 4. **Files and Folders** - Complete file hierarchy for all users Each workflow component has an **Incremental mode** that fetches only events occurring since the last sync. The connector maintains sync state using **cursors** stored in sync points: * `box_cursor_sync_point` - For file/folder events * `user_sync_point` - For user changes * `user_group_sync_point` - For group changes **If no cursor exists for an entity, the connector performs a full sync.** *** ## User Sync Workflow Users are fetched from Box Enterprise API and converted to `AppUser` entities. ### First Sync 1. **Fetch All Users:** Retrieves complete user list from Box Enterprise using pagination. 2. **Process User Data:** Converts Box user objects to `AppUser` format with profile information. 3. **Batch Submission:** Sends all users to `data_entities_processor.on_new_app_users`. 4. **Initialize Cursor:** Saves initial sync point for future incremental syncs. ### Incremental Sync User sync currently operates as a full sync on each run. The connector fetches all active users from Box Enterprise and updates their status in PipesHub. Users marked as inactive in Box will be reflected accordingly in the system. *** ## User Group Sync Workflow ### Full Sync (Initial Run) A full sync executes when no cursor exists: 1. **Fetch All Groups:** Retrieves complete list of enterprise groups from Box API with pagination. 2. **Fetch Group Memberships:** For each group, fetches all members and their roles. 3. **Process Permissions:** Maps Box group roles to PipesHub permission types (Admin, Member). 4. **Batch Processing:** Collects all groups and memberships into a single batch. 5. **Submit to Processor:** Sends the complete batch to `data_entities_processor.on_new_user_groups`. ### Incremental Sync Once a cursor is established, incremental sync processes only new events: 1. **Fetch Events:** Retrieves group-related events from Enterprise Event Stream since last sync. 2. **Process Changes:** Handles various event types: * Group creation and deletion * Group name changes * Membership additions and removals * Role/permission updates 3. **Update State:** Saves the new cursor position for next sync cycle. 4. **Reconciliation:** Periodically validates that all Box groups exist in the database and removes orphaned entries. Groups are only removed after a group listing that reached its last page, so a listing that fails partway never deletes groups. If Box can't return a group's member list during a sync, that group keeps the members PipesHub already has, and the next sync tries again. A failed read never empties a group. Groups and member lists of any size are read page by page to the end. *** ## Record Groups Sync Workflow Record Groups in Box represent user "drives" - the root "All Files" folder (ID: 0) for each user. ### Full Sync 1. **Fetch Active Users:** Retrieves list of all active enterprise users. 2. **Create Record Groups:** For each user, creates a `RecordGroup` representing their root folder. 3. **Set Permissions:** Assigns OWNER permission to each user for their own drive. 4. **Batch Submission:** Sends all record groups to the processor with full permission mappings. ### Incremental Sync Record groups sync operates as a full sync, re-processing all active users to ensure record groups are up-to-date. *** ## Files and Folders Sync Workflow ### Workflow Overview 1. **User Processing:** The connector processes users sequentially to avoid API conflicts when using "As-User" impersonation. 2. **Folder Traversal:** For each user, starts from their root folder (ID: 0) and recursively traverses the entire folder tree. 3. **Change Detection:** During full sync, the connector recursively fetches all items. For incremental sync, it uses the Box Enterprise Event Stream to detect changes. ### Detailed Process #### Initial Sync 1. **Start from Root:** Begins at each user's root folder (All Files). 2. **Recursive Fetch:** For each folder: * Fetches folder contents using `client.folder(folder_id).get_items()` * Processes files and subfolders * Recursively descends into subfolders 3. **Item Processing:** For each item: * **Metadata Extraction:** Collects file/folder properties (name, size, timestamps, path, etag, sha1) * **Permission Fetching:** Retrieves collaborations and sharing settings via `client.folder(id).get_collaborations()` * **Conversion:** Maps Box permissions to PipesHub permission types: * `owner` → OWNER * `co-owner` → OWNER * `editor` → WRITE * `viewer uploader` → WRITE * `previewer uploader` → WRITE * `viewer` → READ * `previewer` → READ 4. **Change Detection:** Compares etag and modified timestamps with existing database records to identify: * New files/folders * Modified content * Moved items * Permission changes 5. **Batch Processing:** Items are batched (default 100 per batch) and sent to: * `data_entities_processor.on_new_records` - For new items * `data_entities_processor.on_record_content_update` - For modifications * `data_entities_processor.on_record_metadata_update` - For metadata changes #### Incremental Sync Box uses a **global Enterprise Event Stream** with a single `stream_position` cursor for all incremental sync operations: 1. **Event Listening:** Monitors event stream for file/folder activities: * `FILE.UPLOADED` * `FILE.DELETED` * `FILE.MOVED` * `FILE.COPIED` * `FOLDER.CREATED` * `FOLDER.DELETED` * `FOLDER.MOVED` * `COLLABORATION.CREATED` * `COLLABORATION.ACCEPTED` * `COLLABORATION.REMOVED` 2. **Event Deduplication:** Groups events by item ID to process each item only once per sync cycle. 3. **Owner Impersonation:** Uses "As-User" header to fetch items on behalf of their owners, ensuring proper permission context. 4. **Parent Folder Validation:** Before processing files, ensures all parent folders exist in the database, creating them recursively if needed. 5. **Targeted Fetching:** For modified items: * Fetches fresh metadata from Box API * Re-processes permissions * Updates database records 6. **Deletion Handling:** A file or folder that is deleted, or moved to the trash, in Box is removed from PipesHub on the next incremental sync. Deleting a folder also removes everything stored under it. Restoring an item from the Box trash syncs it again. If a delete can't be applied, the cursor stays where it was and the delete is retried on the next runs, up to five attempts in all. After the fifth, the batch is passed over with an error in the sync logs, and that item's record stays in PipesHub: a later full sync only walks items that still exist in Box, so it won't remove it. 7. **Stream Position Update:** After processing all events, saves the new `stream_position` cursor for the next incremental sync cycle. This single cursor tracks the state of the entire enterprise event stream, not individual folders. If part of a batch of events couldn't be read, the cursor stays where it was and the same batch is read again on the next run. After five attempts the batch is passed over, with an error in the sync logs, so one item Box keeps failing can't hold back every later change. *** ## Permission & Collaboration Sync Box permissions are managed through **collaborations** - explicit grants that give users or groups access to files and folders. ### Permission Hierarchy 1. **Direct Collaborations:** Explicit permissions set on individual items. 2. **Inherited Permissions:** Permissions flow down from parent folders to children. 3. **Group Memberships:** Users inherit permissions through group collaborations. 4. **Public/Company Links:** Shared links can grant broader access. Sharing never moves a file. A file or folder owned by someone in your Box enterprise stays in its owner's drive, in its place in the owner's folders, and the colleagues it is shared with see it under **Shared with me**. A folder owned by someone outside your enterprise and shared with a colleague is brought in when a full sync finds it in that colleague's folders, and appears only under the colleague's **Shared with me**. A share whose owner is outside the enterprise isn't added any other way: incremental sync and the share-history replay skip it without asking Box for the item, since Box doesn't return such items to a colleague. A single file shared this way never shows up in the colleague's folders, so it isn't brought in at all. ### Sync Process 1. **Fetch Collaborations:** For each file/folder, retrieves all collaborations via API. 2. **Map Accessible By:** Identifies who has access: * Individual users * User groups * Organization-wide (company shared links) * Public (external sharing) 3. **Virtual Groups:** Creates system groups for special access types: * `PUBLIC_ACCESS_GROUP` - For publicly shared items * `ORGANIZATION_ACCESS_GROUP` - For company-wide shared items 4. **Permission Updates:** When collaboration events occur: * Fetches latest collaboration list * Re-processes all permissions for the affected item * Handles recursive permission removal when folder access is revoked 5. **Recursive Revocation:** When a user loses access to a folder: * Removes permissions from the folder * Recursively removes permissions from all descendant files and folders * Ensures access control consistency 6. **Complete collaborator lists:** An item's collaborators are read page by page to the end. If a page fails with a temporary error, the item keeps the access it already has in PipesHub and the next sync fills in the rest. If Box answers a later page with 403 or 404, the pages already read are saved and the rest are not requested again; Box treats that answer as final. ### Share history A full sync also replays past sharing events from Box's enterprise event history (Box keeps up to a year of it), so each person's **Shared with me** is complete. The replay saves its place after each page it reads and applies: * On a large enterprise, it reads up to 200 pages per sync. When it hits that limit, it saves its place and marks the sync incomplete, so the next full sync carries on from there. The whole history is applied within a few syncs of connecting. * Later full syncs resume from the saved place instead of starting again, so only newer history is read. The place is saved only while nothing else in that full sync has failed to read. If something has, the replay still reads its pages but doesn't save its place, so the next full sync replays the same history. When a page of history fails: * **A temporary error**, while fetching the page or applying its events, marks the sync incomplete and stops the replay there. The next full sync reads that page again, and pages saved earlier in the run stay saved. * **A 403 or 404 while fetching a page** stops the replay without marking the sync incomplete, so the sync can still finish and switch to incremental runs. Incremental runs don't replay history, so the rest of it waits for a later full sync. * **A 403 or 404 while applying a page's events** is treated as Box's final answer for that item. The replay carries on, and its place is saved past that page. ### File Extension Filtering The Box connector supports filtering files by extension during sync: 1. **Configuration:** Set allowed file extensions in connector settings (e.g., `.pdf`, `.docx`, `.xlsx`). 2. **Filter Application:** Files are filtered during the sync process based on their extensions. 3. **Folder Handling:** Folders are always synced regardless of filters to maintain proper hierarchy. ### Batch Processing The connector uses intelligent batching to optimize performance: * **Batch Size:** Configurable (default 100 items) * **Concurrent Batches:** Processes multiple batches for different users in parallel * **Rate Limiting:** Respects Box API rate limits (50 requests per second) ### Smart Sync Strategy The connector automatically determines the optimal sync approach: 1. **No Cursor:** Performs full sync 2. **Has Cursor:** Performs incremental sync using event stream 3. **Cursor Expired:** Falls back to full sync and establishes new cursor 4. **Previous full sync incomplete:** If a full sync couldn't read everything (for example, a folder listing or a user's files failed after retries), the cursor isn't saved, and the next run is a full sync again. This keeps changes from being skipped. A 403 or 404 from Box is usually its final answer and doesn't count as incomplete. The exception is a 403 when listing users: without the user list, nobody's files can be walked, so that run is incomplete. ### One sync at a time Scheduled syncs, manual syncs and Box webhooks never run two syncs of the same connector at once. A webhook that arrives while a sync is running queues one follow-up sync, and any more webhooks before it starts are folded into that same run. *** ## Troubleshooting ### Authentication Errors **Problem:** "Failed to fetch access token" or "Invalid credentials" **Solutions:** * Verify Client ID, Client Secret, and Enterprise ID are correct * Ensure the app has been authorized by your Box admin * Check that the app has not been deauthorized in Box Admin Console * Verify your enterprise account is active ### Permission Errors **Problem:** "Insufficient permissions" or "Access denied" **Solutions:** * Ensure all required scopes are enabled in Box Developer Console * Verify "Perform actions as users" is enabled * Check that App Access Level is set to "App + Enterprise Access" * Re-authorize the application if scopes were changed ### No files sync, or group access isn't updated **Problem:** The sync logs say *"Box refused to list users (403), so no one's files can be synced"* or *"Box refused to list groups (403), so group access in PipesHub is not being updated"*. **Solutions:** * For users, turn on the app's **Manage users** scope. For groups, turn on **Manage groups**. Both are under **Administrative Actions** in the Box Developer Console (see Step 2 of **Create Box App**). * Have a Box admin re-authorize the app in the Box Admin Console. Scope changes only take effect after re-authorizing. * Until **Manage users** is fixed, a connector that hasn't finished its first full sync repeats the full sync on every run. No files can be listed, but each run still refreshes groups and replays the same share history (up to 200 pages), because the missing user list keeps the replay from saving its place. A connector that already syncs incrementally keeps its place in the event stream and applies no changes until the user list can be read. If the scope is fixed within 14 days, the first run after the fix applies every change from the gap. After 14 days, Box no longer keeps those events, so the connector runs a full sync instead. That brings in what exists in Box now, and its share-history replay (which reads up to a year back) also applies shares added or removed in the gap, possibly over more than one full sync. Deletions from the gap aren't applied: the full sync doesn't remove records for items that are gone from Box. ### Sync Issues **Problem:** Files not appearing or sync taking too long **Solutions:** * Check the sync logs for specific errors * Verify users are active in Box * Ensure folders are not restricted by admin policies * Try triggering a manual full sync * Adjust batch size if processing large datasets ### Rate Limiting **Problem:** "Rate limit exceeded" errors **Solutions:** * The connector has built-in rate limiting (50 req/s), and retries a rate-limited request after the wait Box asks for * When a file can't be opened because Box keeps rate-limiting, the person sees *"Too many requests to …. Please try again shortly."*, with the connector's name filled in. The wait Box asked for is passed on in the response's `Retry-After` header * Increase sync interval for scheduled syncs * Contact Box support to request higher rate limits for your enterprise *** ## Best Practices ### Sync Strategy * **Use Incremental Sync:** After initial setup, rely on incremental syncs for efficiency * **Schedule Syncs Wisely:** Set sync intervals based on your team's activity patterns. For large datasets, consider running scheduled syncs during off-peak hours ### Filter Configuration * **Be Specific:** Only sync file types you need to index * **Exclude Large Files:** Consider excluding video and large binary files if not needed * **Review Regularly:** Audit your filters to ensure they match current needs ### Monitoring * **Check Logs:** Regularly review sync logs for errors or warnings * **Monitor Performance:** Track sync duration and adjust batch size if needed * **Validate Data:** Periodically verify that critical files are being synced correctly *** ## FAQ There are three common causes: 1. **Email mismatch** - The email used during connector authentication doesn't match your PipesHub account email. This causes permission issues preventing you from accessing synced data. * **Fix:** Reconfigure the connector and authenticate using the same email as your PipesHub account. 2. **Records show in "All Records" but not in search** - Documents display in the All Records section but don't appear in search query results. * **Fix:** Verify sync filters in the connector settings and ensure indexing has completed. Check that the data matches your search query criteria. 3. **Data not yet indexed** - The connector is still syncing or hasn't completed the initial indexing process. * **Fix:** Go to **Settings > Connectors**, check the sync status, and wait for indexing to complete. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.