Skip to main content

​
Overview

The Box integration enables your agents to search, browse, read, upload, and manage files across your enterprise Box environment. Ideal for document retrieval, content analysis, and automated file organization.

​
Features

  • Enterprise Search: Search across file names, descriptions, and file content
  • Document Reading: Extract text from PDFs, DOCX, PPTX, and other document types
  • File Management: Upload, move, copy, and organize files and folders
  • Folder Browsing: Navigate folder hierarchies with sorting and pagination
  • File Downloads: Download files for processing with Python tools

​
Prerequisites

  • Box Enterprise account with admin access
  • A Box Custom App configured for Client Credentials Grant (CCG)
  • Enterprise ID from Box Admin Console

​
Setup Guide

1

Create a Box Custom App

Go to the Box Developer Console, click Create New App, choose Custom App, and select Client Credentials Grant as the authentication method.
2

Configure App Settings

In your app’s Configuration tab:
  • Note the Client ID and Client Secret
  • Under App Access Level, select App + Enterprise Access
  • Under Application Scopes, enable the permissions your agent needs (e.g., Read/Write all files and folders)
3

Authorize the App

In the Box Admin Console, go to Apps > Custom Apps Manager and authorize your newly created app. This requires Box admin privileges.
4

Get Your Enterprise ID

In the Box Admin Console, go to Account & Billing. Your Enterprise ID is displayed at the top of the page.
5

Enable Box Integration

In Aster Agents, navigate to Control Hub > Integrations and locate the Box card. Click Connect and provide:
  • Client ID — from your Box app’s Configuration tab
  • Client Secret — from your Box app’s Configuration tab
  • Enterprise ID — from Box Admin Console
6

Add Tools to Your Agent

Edit your agent and enable the Box tools you need. Available tools cover search, folder browsing, file reading, uploading, and file management.

​
Available Tools

​
Search & Browse

  • Box Search — Full-text search across your enterprise content with filters for file type, extensions, and ancestor folders
  • Box List Folder — Browse folder contents with pagination and sorting

​
Read & Download

  • Box Read File — Extract text content from documents (PDFs, DOCX, PPTX, etc.) using Box’s built-in text extraction
  • Box Get File Info — Get metadata including size, path, owner, dates, and version info
  • Box Download File — Download files as attachments for processing with execute_python

​
Write & Organize

  • Box Upload File — Upload text content as a new file
  • Box Create Folder — Create new folders
  • Box Move Item — Move files or folders to a different location
  • Box Copy Item — Copy files or folders with optional renaming

​
Security Considerations

  • Use a dedicated service account for the Box app rather than a personal account
  • Limit application scopes to only the permissions your agents need
  • Restrict folder access using Box’s collaboration settings to control which content is accessible
  • Monitor app activity in the Box Admin Console under Reports
  • Rotate Client Secret periodically via the Developer Console

​
Troubleshooting

  • Verify your Client ID, Client Secret, and Enterprise ID are correct
  • Confirm the app has been authorized in the Box Admin Console
  • Check that the app is configured for Client Credentials Grant (not OAuth 2.0)
  • The service account user may not have access to the content — use Box collaborations to share folders with the service account
  • Verify the app’s Application Scopes include the required permissions
  • Check that App Access Level is set to “App + Enterprise Access”
  • Box text extraction works best with common document types (PDF, DOCX, PPTX, TXT)
  • Very large files (over 10MB for plain text) may not be fully extracted
  • Scanned PDFs require Box’s OCR feature to be enabled for your enterprise
  • Box Search (box_search) - Search enterprise content
  • Box List Folder (box_list_folder) - Browse folder contents
  • Box Read File (box_read_file) - Extract text from documents