1. Ema v2 Docs
  2. Integrations Data
  3. Data Connectors Box

Box Connector

The Box connector syncs files from Box into a Knowledge base so an AI Employee (AIE) can search and cite that content. It reaches Box through the Box Content API and authorizes with OAuth2 — you sign in with your Box account and approve read access.

You set up a Box connection from the Data sources tab of the Integrations page. Creating a connection is admin-only — builders never see credentials; they reference the resulting Knowledge base when configuring a workflow.

What it ingests

The connector walks the Box folders you scope it to, recursively, and ingests each file it finds. For each file it captures the Box file ID, name, folder path, size, the etag (used for incremental sync), and a MIME type inferred from the file's extension. Files then flow through the shared ingestion pipeline (extract → chunk → embed → store) described in Data Connectors.

How to connect

Box uses the OAuth2 authorization-code flow with a platform-level Box app — there are no client credentials for you to manage. This mode is available only when Box OAuth2 is configured on your Ema platform; the form shows a notice when it isn't. To connect:

  1. Open the Data sources tab and select the Box tile.
  2. Enter a connection name (you can create several connections for different Box accounts or departments).
  3. Select Connect with Box. Ema redirects you to Box's authorization page with a signed state parameter for CSRF protection.
  4. Review and approve the requested read access, then Box redirects back to Ema, which exchanges the code for tokens, stores them encrypted, and creates the connection automatically.

Box plan. Box OAuth2 app connections require a Box Business plan or above. On a free plan, ask your Box admin to upgrade before connecting.

Token refresh. Box rotates the refresh token on each use. Ema refreshes the access token before each sync and persists the rotated refresh token, so connections keep working across restarts without manual re-authentication.

Sync configuration

Scope and schedule are set on the Knowledge base built from the connection. One connection can feed several Knowledge bases scoped to different folders.

Folder scope

Box syncs only the folders you point it at — there is no default "sync everything" behavior. In the Knowledge base's Folder scope card, add one or more Box folder URLs (of the form https://app.box.com/folder/<id>). Ema extracts the numeric folder ID from each URL and syncs that folder's tree. Until at least one folder URL is added, syncs are skipped. If you supply folder URLs but none are valid, the sync reports an error rather than silently falling back to the whole account.

Schedule

In the Knowledge base's Sync configuration, set:

  • Sync enabled — turn syncing on or off.
  • Schedule — Interval (sync automatically, in minutes) or Manual (only on demand).
  • Sync now — trigger a one-off sync at any time.

Syncs are incremental: the connector compares each file's etag against the stored content hash and skips unchanged files, so re-syncs only process what changed.

Limits and behavior

  • Read-only. The connection requests read access to your Box content — the connector never writes back to Box.
  • Supported file types only. Extractable types are PDF; Word, Excel, and PowerPoint (.docx, .xlsx, .pptx); plain text, Markdown, CSV, HTML, and JSON; and images (.png, .jpg, .webp, .gif) read via a vision model. Other types are counted as unsupported and skipped.
  • Maximum file size. Individual files larger than 500 MB are skipped with a validation error.
  • Maximum folder depth. The connector traverses up to 50 levels of nested folders.
  • Scope is required. Box syncs only the folders you scope by URL; it does not crawl the whole account by default. A Knowledge base with no folder URLs is skipped until you add one.
  • Access-bound. Within the folders you scope, the connector sees only what the authorized Box account can access.

What's next

Last updated: Aug 27, 2026