Box
The Box source ingests files from a Box enterprise. Starting at folder_id, the
connector walks every descendant subfolder, and each file becomes a record in
the pipeline. Its contents are uploaded to a new agent session for processing.
Each file inherits its Box collaborations as document-level ACL.
Authentication
Before you create the pipeline, set up your Box app. Box uses server-to-server
authentication via the OAuth 2.0 Client Credentials Grant. In the
Box Developer Console, create a Custom
App with Server Authentication (Client Credentials Grant), then copy its
client_id and client_secret and your enterprise_id.
Grant the app the access it needs:
- Application Scopes: enable Read all files and folders stored in Box. The connector only reads folders, files, and collaborations, so no write, user-management, or admin scopes are required.
- App Access Level: set App + Enterprise Access so the app can reach the enterprise and user-owned content you want to ingest.
- Authorize the app in the Box Admin Console. Client Credentials Grant apps do not work until an enterprise admin approves the app's client ID.
Grant only the read scope above. The connector never writes to Box and never calls user, group, webhook, retention, or admin APIs.
Configuration
SOURCE FIELD (BOX)
Code example with json syntax.1
Fields
| Field | Required | Description |
|---|---|---|
type | Yes | box. |
auth | Yes | Box API credentials. See Authentication. |
folder_id | No | The Box folder ID to ingest from. A Box folder URL (https://app.box.com/folder/<id>) is also accepted, in which case the ID is taken from the URL. Defaults to the enterprise root (ID "0"). |
auth fields
| Field | Required | Description |
|---|---|---|
type | Yes | ccg. |
client_id | Yes | Box app client ID. |
client_secret | Yes | Box app client secret. Encrypted at rest and never returned in responses. |
enterprise_id | Yes | Box enterprise ID the app is authorized for. |
How records are fetched
Each run enumerates the folder subtree breadth-first, starting at folder_id.
Subfolders are always recursed regardless of watermark, so files newly added to
older folders are still discovered. Each file becomes one record; folder entries
are not records themselves.
Source metadata
Each record carries source metadata that the connector resolves at fetch time.
system_metadata:
| Key | Description |
|---|---|
name | The file name. |
size | File size in bytes. |
modified_at | The file's last-modified timestamp. |
created_at | The file's created timestamp. |
sha1 | The file's SHA-1 content hash. |
etag | The file's ETag. |
parent_id | The ID of the file's parent folder. |
user_metadata is empty for Box.
acl_metadata holds each file's effective grants in the source-independent
ACL metadata shape. A file's
effective ACL is the union of its parent folder's cumulative collaborations
(merged up the folder chain) and the file's own collaborations, shared link, and
owner. Box has no notion of comment access, so commenters and
group_commenters are always null. Box collaboration roles map to buckets as
follows:
| Bucket | Box grant |
|---|---|
owners | The file owner, and collaborators with the owner role |
editors | User collaborators with editor or co-owner |
readers | User collaborators with viewer, viewer uploader, previewer, or previewer uploader |
group_editors | Group collaborators with editor or co-owner |
group_readers | Group collaborators with a read role |
public_access | A shared link whose effective access is open (READER) |
org_wide_access | A shared link whose effective access is company (READER) |
If a collaboration read returns 403 or 404 while resolving ACL, the
connector emits no grants for that item rather than failing the run. It fails
closed: the resolved ACL reflects less access than Box actually allows, never
more. A persistent 403 usually means the app's service account lacks access to
that item.
Incremental sync
When sync_mode is incremental (the default), the pipeline tracks a watermark
based on each file's modified_at timestamp. See
Sync mode. On the next run, only
files modified since the stored watermark are reprocessed.
Deletes are not propagated. A file the connector can no longer retrieve stops appearing in new runs. The pipeline emits no delete signal, so anything a previous run already produced downstream — for example, a document indexed into a corpus — is left in place.