> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reducto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hybrid VPC — Box

> Set up Hybrid VPC with Box as your document storage backend

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

```mermaid theme={null}
flowchart LR
    subgraph customer["Customer Box Environment"]
        direction TB
        folder["Box Folder<br/>(documents, artifacts)"]
        app["Box Custom App<br/>(CCG auth)"]
        app --> folder
    end

    subgraph reducto["Reducto Infrastructure"]
        direction TB
        workers["Compute Workers"]
        api["Reducto API + Database"]
        workers --> api
    end

    workers <--> folder
```

## Setup

<Steps>
  <Step title="Create a Box Custom Application">
    1. Go to the [Box Developer Console](https://app.box.com/developers/console)
    2. Click **Create New App** → **Custom App**
    3. Select **Server Authentication (Client Credentials Grant)** as the authentication method
    4. Name the app (e.g., "Reducto Integration")
    5. Click **Create App**
  </Step>

  <Step title="Configure app permissions">
    In the app's **Configuration** tab:

    1. Under **Application Scopes**, enable:
       * **Read all files and folders stored in Box**
       * **Write all files and folders stored in Box**
    2. Under **App Access Level**, select **App + Enterprise Access**
    3. Click **Save Changes**
  </Step>

  <Step title="Authorize the app in Admin Console">
    1. Go to [Box Admin Console](https://app.box.com/master) → **Apps** → **Custom Apps**
    2. Click **Add App**
    3. Enter the **Client ID** from your app's Configuration tab
    4. Click **Authorize**

    <Warning>
      This step requires Box Enterprise Admin privileges. If you're not an admin, ask your Box admin to authorize the app.
    </Warning>
  </Step>

  <Step title="Create a dedicated folder">
    Create a folder in Box for Reducto to use:

    1. In Box, create a new folder (e.g., "Reducto Processing")
    2. Note the **Folder ID** from the URL (e.g., `https://app.box.com/folder/123456789` → folder ID is `123456789`)
    3. Ensure the service account (created automatically with your app) has access to this folder

    <Note>
      If you want Reducto to access the root of the enterprise, use folder ID `0`. For better isolation, we recommend creating a dedicated folder.
    </Note>
  </Step>

  <Step title="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                                         |
  </Step>
</Steps>

## 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`     | Target folder ID for document storage (use `0` for root) |

## How It Works

1. **Authentication**: Reducto authenticates using Client Credentials Grant (CCG) — no user interaction required. The app's service account gets an access token automatically.

2. **Document storage**: Files are stored in the configured Box folder using the processing key as the filename. Reducto creates, reads, and deletes files as needed during processing.

3. **Result access**: Processing results are written back to Box. You can access them via shared links (similar to presigned URLs) or by browsing the folder in Box.

## Data Lifecycle

Box does not have built-in lifecycle expiration like S3 or Azure. To manage data retention:

<AccordionGroup>
  <Accordion title="Option 1: Reducto-managed cleanup (recommended)">
    Reducto automatically deletes intermediate artifacts after processing completes. Configure the retention period during onboarding.
  </Accordion>

  <Accordion title="Option 2: Box retention policies">
    Box Enterprise supports [retention policies](https://support.box.com/hc/en-us/articles/360043697334-Managing-Retention-Policies) that can auto-delete content after a specified period. Set up a retention policy on the Reducto folder.
  </Accordion>

  <Accordion title="Option 3: Manual cleanup">
    Periodically review and delete files from the Reducto folder. Not recommended for production use.
  </Accordion>
</AccordionGroup>

## Security

* **No user credentials required**: CCG authentication uses app-level credentials, not user passwords
* **Scoped access**: The app can be restricted to specific folders using Box's collaboration model
* **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**: Client Secret can be rotated in the Box Developer Console without downtime

## 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                | Use Box retention policies or Reducto-managed cleanup   |

## Troubleshooting

<AccordionGroup>
  <Accordion title="403 Forbidden when accessing files">
    Verify that:

    1. The app is authorized in the Box Admin Console
    2. The service account has collaborator access to the target folder
    3. The app scopes include read and write permissions
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>