Hybrid VPC — Box

This guide covers setting up Hybrid VPC with Box as your storage backend. Reducto uses a Box enterprise application with Client Credentials Grant (CCG) to read and write documents in your Box environment. This integration is ideal for organizations that already manage documents in Box and want to process them with Reducto without moving data to a separate object store.

Prerequisites

Box Enterprise account with admin access
Box Developer Console access for creating custom apps
Values provided during onboarding from Reducto (Organization ID)

Architecture

Setup

Create a Box Custom Application

Go to the Box Developer Console
Click Create New App → Custom App
Select Server Authentication (Client Credentials Grant) as the authentication method
Name the app (e.g., “Reducto Integration”)
Click Create App

Configure app permissions

In the app’s Configuration tab:

Under Application Scopes, enable:
- Read all files and folders stored in Box
- Write all files and folders stored in Box
Under App Access Level, select App Access Only. Reducto signs in as the app’s service account and never acts as another user, so it does not need App + Enterprise Access
Click Save Changes

Authorize the app in Admin Console

Go to Box Admin Console → Apps → Custom Apps
Click Add App
Enter the Client ID from your app’s Configuration tab
Click Authorize

This step requires Box Enterprise Admin privileges. If you’re not an admin, ask your Box admin to authorize the app.

Create a dedicated folder

Create a folder in Box for Reducto to use:

In Box, create a new folder (e.g., “Reducto Processing”)
Note the Folder ID from the URL (e.g., https://app.box.com/folder/123456789 → folder ID is 123456789)
Invite the app’s service account (created automatically with your app, listed in the app’s General Settings as AutomationUser_...@boxdevedition.com) to the folder as an Editor. Reducto uploads, lists, and versions files in this folder

Folder ID 0 is the root of the app’s service account, not the root of your enterprise. Files that Reducto writes there are visible only to the service account. Reducto uses 0 when you do not provide a folder ID, so we recommend a dedicated folder.

Share credentials with Reducto

From the app’s Configuration tab, securely share:

Value	Where to find
Client ID	Configuration → OAuth 2.0 Credentials
Client Secret	Configuration → OAuth 2.0 Credentials
Enterprise ID	General Settings → Enterprise ID (or Admin Console → Account & Billing)
Folder ID	URL of the target folder in Box
Data residency	`us`, `eu`, or `au`: the Reducto region that processes your documents

Integration Values

Value	Description
`client_id`	Box app OAuth 2.0 Client ID
`client_secret`	Box app OAuth 2.0 Client Secret
`enterprise_id`	Your Box Enterprise ID
`folder_id`	Numeric ID of the folder where Reducto writes files. Optional, defaults to `0` (the service account’s root)
Data residency	`us`, `eu`, or `au`: the Reducto region that processes your documents

Box has no region setting in Reducto. The data residency value decides which Reducto region processes your documents. Send requests to that region’s API (https://platform.reducto.ai, https://eu.platform.reducto.ai, or https://au.platform.reducto.ai).

Environments

Reducto registers your values as a Hybrid VPC environment for your organization. One organization can have more than one environment, for example one Box folder per data residency or per client. Select an environment per request with settings.hybrid_vpc.environment (see Multiple Environments). For /parse, set settings.hybrid_vpc.environment. For /extract and /split, set it under parsing: parsing.settings.hybrid_vpc.environment. Their top-level settings object ignores hybrid_vpc. For example, the relevant part of an /extract request body:

{
  "input": "box://123456789",
  "parsing": { "settings": { "hybrid_vpc": { "environment": "client-a" } } }
}

How It Works

Authentication: Reducto authenticates using Client Credentials Grant (CCG) — no user interaction required. The app’s service account gets an access token automatically.
Document storage: Uploads, results, and intermediate artifacts are stored in the configured Box folder. Reducto names each file after its storage key and refers to it by its Box file ID afterward. When a file with the same name already exists, Reducto uploads a new version of that file.
Result access: Result and image URLs in API responses are Box web-app links of the form https://app.box.com/file/<file_id>. They are not shared links and do not expire. To open one, sign in to Box as a user who has access to the Reducto folder, or browse the folder in Box.

Processing an Existing Box File

Pass a Box file ID explicitly with the box:// scheme:

from reducto import Reducto

client = Reducto()
result = client.parse.run(input="box://123456789")

import Reducto from "reductoai";

const client = new Reducto();
const result = await client.parse.run({ input: "box://123456789" });

curl -X POST "https://platform.reducto.ai/parse" \
  -H "Authorization: Bearer $REDUCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":"box://123456789"}'

Reducto retrieves the file using the Box credentials configured for your Hybrid VPC organization. The file can be in any folder, but the app’s service account must be able to read it, for example as a collaborator on that folder. box:// inputs work only for organizations with Box Hybrid VPC storage. Use box:// rather than an app.box.com web URL, which is intended for an interactive browser session. The same input works with /extract and /split. To process a specific historical version, add the Box file-version ID as a query parameter:

box://123456789?version=987654321

The version value is the immutable Box file-version ID, not the human-facing version number. If omitted, Reducto processes the file’s current version. The file ID and version ID must both be numeric, and version is the only query parameter accepted.

Data Lifecycle

Box does not have built-in lifecycle expiration like S3 or Azure, and Reducto does not delete the files it writes to your Box folder. The job and upload deletion endpoints (DELETE /job/{job_id} and DELETE /upload/{file_id}) support only S3-backed storage and do not remove files from Box. To manage data retention:

Option 1: Box retention policies (recommended)

Box Enterprise supports retention policies that can auto-delete content after a specified period. Set up a retention policy on the Reducto folder. Keep source documents that you want to retain outside the Reducto folder.

Option 2: Manual cleanup

Periodically review and delete files from the Reducto folder. Not recommended for production use.

Security

No user credentials required: CCG authentication uses app-level credentials, not user passwords
Scoped access: The service account can read and write only the content it owns or is a collaborator on, so you control access with Box collaborations
Enterprise admin approval: The app must be explicitly authorized by a Box admin
Audit trail: Box provides detailed audit logs of all file access and modifications
Credential rotation: When you reset the Client Secret in the Box Developer Console, send the new secret to Reducto. Requests fail until Reducto has the new secret

Limitations

Limitation	Impact	Mitigation
No Terraform provider	Setup is manual (not automated via IaC)	Documented step-by-step process above
Rate limits	Box API has more aggressive rate limits than S3/Azure	Reducto handles rate limiting and retries automatically
File-based API	Box uses file/folder hierarchy, not flat key-value	Reducto maps keys to filenames transparently
No native lifecycle expiry	Unlike S3, no automatic per-object TTL, and Reducto does not delete Box files	Use Box retention policies

Troubleshooting

Errors for box:// inputs

Box response or input	Reducto error
Malformed URI (non-numeric file ID, a path, or a query parameter other than a numeric `version`)	`400`: `Invalid Box URL format - use box://file-id or box://file-id?version=file-version-id`
Organization without Box Hybrid VPC storage	`400`: `Box URLs require Box Hybrid VPC storage`
Box returns `401` or `403`	`400`: `Access denied reading the Box file. Check that the configured Box application can read it.`
Box returns `404`	`404`: the Box file was not found
Box returns `408`, `429`, or `5xx`, or the connection fails	Retried as a temporary failure. If it persists, `503`: `Document download is temporarily unavailable. Please retry shortly.`

403 Forbidden when accessing files

Verify that:

The app is authorized in the Box Admin Console
The service account has collaborator access to the target folder
The app scopes include read and write permissions

Rate limit errors (429)

Reducto handles rate limiting automatically with exponential backoff. If you see persistent rate limit errors, contact Reducto support — we may need to adjust concurrency settings for your account.

Files not appearing in Box web UI

Files created by the service account are owned by that account. To view them in the Box web UI, add yourself as a collaborator on the Reducto folder, or use the service account’s credentials to browse.

Get Started

Developer Tools

Core Functions

Workflows and Pipelines

Configurations

Reference

Components

Enterprise Resources

Security and privacy

On-premise Resources

Hybrid VPC — Box

Prerequisites

Architecture

Setup

Integration Values

Environments

How It Works

Processing an Existing Box File

Data Lifecycle

Security

Limitations

Troubleshooting

​Prerequisites

​Architecture

​Setup

​Integration Values

​Environments

​How It Works

​Processing an Existing Box File

​Data Lifecycle

​Security

​Limitations

​Troubleshooting

Prerequisites

Architecture

Setup

Integration Values

Environments

How It Works

Processing an Existing Box File

Data Lifecycle

Security

Limitations

Troubleshooting