Box Connector

The Box connector allows you to read documents from and write converted outputs to an IBM Box account. Use it as both a source (to read documents for conversion) and a target (to write converted results).

Prerequisites

• Box Account: A Box account with access to a Developer Console
• Box Platform App: A custom app created in the Box Developer Console, configured for either Client Credentials Grant (CCG) or JWT authentication
• Client ID and Secret: Generated for your Platform App

Setup and Authentication

1. Create a Box Platform App

1. Log in to the Box Developer Console
2. Click New App
3. Choose a Server app
4. Name your app and create it
5. Select an authentication method:
   • Client Credentials Grant (CCG) - simpler, service-account-style auth
   • JWT (Server Authentication) - stricter, requires an RSA keypair
6. Under App Details in the Configuration tab, copy the Client ID and fetch the Client Secret (may need 2FA enabled)
7. If prompted, submit the app for admin approval (if you are a non-admin in an enterprise account)

See Box's Client Credentials Grant setup guide and JWT setup guide for more detailed walkthroughs.

2. Choose an Identity: enterprise_id or user_id

The connector authenticates as exactly one of the following (both source and target configuration require exactly one to be set):

• enterprise_id: Authenticates as the app's enterprise-scoped service account. This service account has no access to your files by default — you must explicitly share the folders/files you want the connector to read or write with the service account. The exact service account identity is visible under the Platform App's Properties.
• user_id: Impersonates a specific Box user directly (a Managed User or Admin), rather than acting as an enterprise-scoped service account. This requires the app's Configuration tab to have both App + Enterprise Access and Generate User Access Tokens enabled. Like enterprise_id, the value is visible under the Platform App's Properties.

3. Find Folder and File IDs

Folder and file IDs can be parsed directly from a Box URL:

• https://app.box.com/file/{123} → file ID is 123
• https://app.box.com/folder/{456} → folder ID is 456

4. (JWT only) Download and Map Credentials

If you chose JWT authentication, download the app's credentials JSON from the Developer Console (Configuration tab → Generate Keypair). This file's fields map to the connector's config fields as follows:

jwt_key_id, private_key, and private_key_passphrase must all be provided together — the connector infers JWT mode once these are set, and falls back to CCG mode when they're omitted.

Configuration

The Box connector can be used as both a source and target in the Batch API.

Required Parameters

* Exactly one of enterprise_id or user_id must be provided — not both, and not neither.

Optional Parameters (JWT Authentication)

* jwt_key_id, private_key, and private_key_passphrase must all be provided together for JWT authentication, or all omitted for CCG.

Optional Parameters (Folder/File Selection)

Connector-Specific Behavior

As a Source

• Folder traversal: folder_id defaults to "0" (root); subfolders are traversed recursively to enumerate files
• Explicit file selection: Setting file_ids overrides folder traversal entirely — the connector processes only those files and does not also read from folder_id
• Limits enforced during traversal: max_num_elements stops enumeration as soon as the cap is reached, rather than listing the entire tree and truncating afterward

As a Target

• Writes into folder_id: Defaults to the root folder ("0")
• Creates output subfolders as needed: Nested output paths (e.g. json/, md/) are created automatically under the target folder
• Version-safe uploads: If a file with the same name already exists at the destination, the connector uploads the new content as a new Box file version

Security and Permissions

Platform App Access

• CCG or JWT — either is supported; JWT requires an additional RSA keypair registered with the app
• Creating the Platform App requires enterprise admin approval, unless you are an admin/co-admin
• To use user_id impersonation, the app must have App + Enterprise Access and Generate User Access Tokens enabled on its Configuration tab

Content Access

• If using enterprise_id, the service account has no access to content until you explicitly share the relevant folders/files with it
• If using user_id, the connector sees exactly what that impersonated user can see in Box

Limitations

• No pattern/glob filtering: The connector processes all files under folder_id (or all of file_ids) — there is no filename or MIME-type filtering
• JWT dependency: JWT authentication requires the box extra (boxsdk[jwt]) to be installed alongside the base Box SDK dependency

Usage Examples

There are three main ways to interface with the connectors. All use the same underlying POST /v1/convert/source/batch endpoint.

Tasks UI

Navigate to the Tasks view and select "Create Task +". Select Batch as the task type (connectors use batch tasks, not single).

Fill in the fields as prompted. They should correspond to the fields gathered above (excluding 'kind').

Box as a Source

(UI coming soon)

Box as a Target

(UI coming soon)

REST API

curl -X POST "${DOCLING_SERVICE_URL}/v1/convert/source/batch" \
  -H "X-Api-Key: ${DOCLING_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": [
      {
        "kind": "box",
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET",
        "enterprise_id": "YOUR_ENTERPRISE_ID",
        "folder_id": "123456789",
        "max_num_elements": 100
      }
    ],
    "target": {
      "kind": "box",
      "client_id": "YOUR_CLIENT_ID",
      "client_secret": "YOUR_CLIENT_SECRET",
      "enterprise_id": "YOUR_ENTERPRISE_ID",
      "folder_id": "987654321"
    },
    "options": {
      "to_formats": ["md", "json"]
    }
  }'

Using JWT Authentication

curl -X POST "${DOCLING_SERVICE_URL}/v1/convert/source/batch" \
  -H "X-Api-Key: ${DOCLING_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": [
      {
        "kind": "box",
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET",
        "enterprise_id": "YOUR_ENTERPRISE_ID",
        "jwt_key_id": "YOUR_PUBLIC_KEY_ID",
        "private_key": "-----BEGIN ENCRYPTED PRIVATE KEY-----...-----END ENCRYPTED PRIVATE KEY-----",
        "private_key_passphrase": "YOUR_PASSPHRASE",
        "file_ids": ["111111", "222222"]
      }
    ],
    "target": {
      "kind": "presigned_url"
    },
    "options": {
      "to_formats": ["md"]
    }
  }'

Python SDK

from docling.service_client import DoclingServiceClient
from docling.datamodel.service.requests import GenericSourceRequest
from docling.datamodel.service.targets import GenericTargetRequest
import os

SERVICE_URL = os.getenv("DOCLING_SERVICE_URL")
API_KEY = os.getenv("DOCLING_API_KEY")
BOX_CLIENT_ID = os.getenv("BOX_CLIENT_ID")
BOX_CLIENT_SECRET = os.getenv("BOX_CLIENT_SECRET")
BOX_ENTERPRISE_ID = os.getenv("BOX_ENTERPRISE_ID")

# Box source
source = GenericSourceRequest(
    kind="box",
    client_id=BOX_CLIENT_ID,
    client_secret=BOX_CLIENT_SECRET,
    enterprise_id=BOX_ENTERPRISE_ID,
    folder_id="123456789",
    max_num_elements=100
)

# Box target
target = GenericTargetRequest(
    kind="box",
    client_id=BOX_CLIENT_ID,
    client_secret=BOX_CLIENT_SECRET,
    enterprise_id=BOX_ENTERPRISE_ID,
    folder_id="987654321"
)

with DoclingServiceClient(url=SERVICE_URL, api_key=API_KEY) as client:
    job = client.submit_batch(
        sources=[source],
        target=target,
        output_formats=["md", "json"]
    )

    # Wait for completion
    response = job.result()
    print(f"Processed {response.num_converted} documents")
    print(f"Succeeded: {response.num_succeeded}")
    print(f"Failed: {response.num_failed}")

Related Documentation

• Batch API Reference - Complete batch endpoint documentation
• Connectors Overview - All available connectors
• Box Developer Console - Create and manage Platform Apps
• Client Credentials Grant Setup - Official Box CCG authentication guide
• JWT Setup - Official Box JWT authentication guide