# How to Integrate Retool with Box

- Tool: Retool
- Difficulty: Intermediate
- Time required: 25 minutes
- Last updated: April 2026

## TL;DR

Connect Retool to Box using a REST API Resource. Configure Box's API base URL and OAuth 2.0 JWT (server-to-server) credentials in Retool's Resources tab, then build queries to browse folders, list files, upload and download documents, search content, and manage permissions. All requests proxy through Retool's backend, keeping Box credentials off the client and eliminating CORS issues for this enterprise file management integration.

## Why Connect Retool to Box?

Box is the enterprise standard for content management in heavily regulated industries — legal, financial services, healthcare, and government organizations use Box for its compliance certifications (FedRAMP, HIPAA, SOC 2), granular permission controls, version history, and eSignature integrations. Teams that store critical business documents in Box often need internal tools to browse, manage, route, and act on those documents without requiring everyone to have Box accounts or navigate Box's full interface.

A Retool + Box integration enables a range of internal workflows: document review panels where case managers can browse Box folders by client or matter, upload new documents, and update metadata without logging into Box directly; approval workflows that surface Box documents in a Retool interface with approve/reject buttons that move files between Box folders; contract management dashboards that list Box documents by contract type with expiration date metadata and collaboration access controls; and audit tools that query Box file access logs and permission data for compliance reporting.

Box's JWT server-to-server authentication is the right choice for Retool integrations because it allows Retool to access Box as a service account without requiring individual users to OAuth-authorize Box through Retool. This works well for internal tools where Retool admins manage a service account with appropriate Box permissions, and all Retool users operate under that service account's access level.

## Before you start

- A Box Business, Business Plus, or Enterprise account (JWT authentication requires Enterprise or higher for production use)
- Admin access to the Box Admin Console to create and authorize a Custom App
- A Retool account (Cloud or self-hosted) with permission to create Resources
- Knowledge of the Box folder IDs you want to access (visible in Box's web URL when browsing a folder)
- Familiarity with Box's permission model (collaborations, access levels: viewer, previewer, uploader, editor, co-owner, owner)

## Step-by-step guide

### 1. Create a Box JWT App in the Box Developer Console

Box's server-to-server JWT authentication requires creating a Custom App in the Box Developer Console. This creates a service account that Retool uses to access Box on behalf of the integration.

Navigate to the Box Developer Console at app.box.com/developers/console. Click Create New App. Select Custom App as the app type. Choose Server Authentication (with JWT) as the authentication method. Give the app a descriptive name like 'Retool Integration'.

After creating the app, you'll be in the app configuration. In the Configuration tab, under Application Scopes, select the permissions your Retool integration needs. Common scopes for a document management integration:
- Read all files and folders stored in Box (for browsing and downloading)
- Write all files and folders stored in Box (for uploads and moves)
- Manage users (only if your app needs to manage Box user accounts)
- Manage groups and collaborations (for managing folder sharing)

In the Add and Manage Public Keys section, generate a new RSA key pair. Box will generate a public/private key pair and prompt you to download the app configuration JSON file — this JSON file contains your Client ID, Client Secret, and private key in a single download. Save this JSON file securely — it contains all the credentials needed to authenticate.

Return to the Box Admin Console (admin.box.com) to authorize the app. Go to Enterprise Settings → Apps → Custom Apps Manager. Find your newly created app and click Authorize. This grants the JWT app access to your Box enterprise account. Without this authorization step, the JWT app cannot access any Box content.

After authorization, note the Service Account user email that Box creates for the JWT app (visible in the Admin Console → Users). You'll need to give this service account access to the specific Box folders you want Retool to access by adding it as a collaborator.

**Expected result:** A Box JWT Custom App is created and authorized in the Box Admin Console. You have the JSON configuration file containing the JWT app credentials. The service account has been added as a collaborator on the relevant Box folders.

### 2. Configure the Box REST API Resource in Retool

Box's JWT authentication requires obtaining an OAuth 2.0 access token using the RSA private key before making API calls. Retool's Custom Authentication feature handles this multi-step flow: it first calls Box's token endpoint to get an access token, then uses that token in subsequent API requests.

In Retool, navigate to the Resources tab and click Add Resource. Select REST API.

Name the resource 'Box Enterprise API' and set the Base URL to https://api.box.com.

In the Authentication section, select Custom Auth. This allows Retool to run a pre-authentication step before each API call. In the Auth Steps section, add a step of type Request. Configure this step to call Box's token endpoint:
- Method: POST
- URL: https://api.box.com/oauth2/token
- Body (JSON): include grant_type, client_id, client_secret, and the JWT assertion. The JWT assertion must be generated from the RSA private key in Box's configuration file.

Because Box's JWT token generation requires signing a JWT with an RSA private key — which involves cryptographic operations that Retool's REST API resource cannot do natively — the recommended approach for Retool Cloud is to use a small intermediary service (such as a Retool Workflow, an AWS Lambda, or a simple Express.js endpoint) that handles the JWT signing and returns an access token. This token endpoint is then called from Retool's Custom Auth step.

For simpler setup, use Basic Auth with a Box Developer Token (generated in the Box Developer Console → app configuration → Developer Token section). Developer Tokens expire after 60 minutes and are suitable for testing but not production use.

For production: store all Box credentials (client_id, client_secret, private key JSON) in Retool's Configuration Variables as secrets. Reference them via {{ configVars.BOX_CLIENT_ID }} in the resource configuration.

```
// Box JWT Token Generator — deploy as a Retool Workflow or serverless function
// This generates a Box access token using JWT authentication
// Called by Retool's Custom Auth step

// Required: Box JWT configuration values as environment variables
// BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_ENTERPRISE_ID, BOX_PRIVATE_KEY, BOX_KEY_ID, BOX_PASSPHRASE

const jwt = require('jsonwebtoken');
const axios = require('axios');

async function getBoxToken() {
  const privateKey = process.env.BOX_PRIVATE_KEY.replace(/\\n/g, '\n');
  
  const jwtClaims = {
    iss: process.env.BOX_CLIENT_ID,
    sub: process.env.BOX_ENTERPRISE_ID,
    box_sub_type: 'enterprise',
    aud: 'https://api.box.com/oauth2/token',
    jti: require('crypto').randomBytes(16).toString('hex'),
    exp: Math.floor(Date.now() / 1000) + 30
  };
  
  const assertion = jwt.sign(jwtClaims, {
    key: privateKey,
    passphrase: process.env.BOX_PASSPHRASE || ''
  }, {
    algorithm: 'RS256',
    keyid: process.env.BOX_KEY_ID
  });
  
  const response = await axios.post('https://api.box.com/oauth2/token', {
    grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
    assertion,
    client_id: process.env.BOX_CLIENT_ID,
    client_secret: process.env.BOX_CLIENT_SECRET
  });
  
  return response.data.access_token;
}
```

**Expected result:** The Box REST API resource is configured in Retool. Test queries using an initial Developer Token return 200 responses from the Box API. For production, the JWT token generation flow is in place.

### 3. Build queries to browse folders and list Box files

With the Box REST API resource configured, create queries to browse Box's folder hierarchy. Box uses folder IDs as the primary identifier — every Box folder has a unique numeric ID visible in the Box web URL when you browse to that folder.

Create a query named getFolderContents. Set Method to GET. Set URL Path to /2.0/folders/{{ folderId.value || '0' }}/items — folder ID '0' is the root folder (All Files). Set URL Parameters to include fields: name,type,size,modified_at,modified_by,item_status and limit: 200.

The response contains a total_count and an entries array with file and folder objects. Create a JavaScript transformer to reshape the entries for display in a Retool Table component.

For a folder breadcrumb navigation: create a separate query named getFolderInfo using GET /2.0/folders/{{ currentFolderId.value }}, which returns the folder's path_collection (an array of parent folders). Use a transformer to build a breadcrumb string from this array.

For browsing nested folders: when a user clicks on a folder row in the Table, update a state variable folderId with the clicked folder's ID and re-trigger the getFolderContents query. Use a 'Click folder' event handler in the Table component to set the state variable. Add a Back button that navigates to the parent folder ID from the breadcrumb path.

For displaying file type icons: use Box's type field (file or folder) combined with the file extension from the file name. Add a column to your transformer that maps extensions to icon names from Retool's icon library.

```
// getFolderContents transformer
// Input: data (Box folder items response)
const entries = data?.entries || [];

return entries.map(item => ({
  id: item.id,
  name: item.name,
  type: item.type, // 'file' or 'folder'
  extension: item.type === 'file' ? item.name.split('.').pop()?.toLowerCase() : null,
  size: item.type === 'file' && item.size
    ? item.size < 1024 ? `${item.size} B`
    : item.size < 1048576 ? `${(item.size / 1024).toFixed(1)} KB`
    : `${(item.size / 1048576).toFixed(2)} MB`
    : '—',
  modifiedAt: item.modified_at
    ? new Date(item.modified_at).toLocaleDateString('en-US', { year: 'numeric', month: 'short', day: 'numeric' })
    : '—',
  modifiedBy: item.modified_by?.name || '—',
  status: item.item_status || 'active'
}));
```

**Expected result:** The Table component shows Box folder contents with file names, types, sizes, and modification dates. Clicking a folder row navigates into that folder. The breadcrumb shows the current path within the Box folder hierarchy.

### 4. Implement file upload and download in Retool

Box's file upload API uses a multipart form upload to a different base URL (upload.box.com) than the standard API. Retool's FilePicker component provides the file binary data for upload.

For file upload: create a query named uploadToBox. Set Method to POST. Set the full URL to https://upload.box.com/api/2.0/files/content (Box uploads use a different subdomain from the main API). Set the Body Type to Form Data. Add the attributes field as a JSON string and the file field referencing the FilePicker component.

The attributes field must contain the destination folder ID and the desired filename. Structure it as a JSON-encoded string: { "name": "{{ filePicker1.value[0].name }}", "parent": { "id": "{{ currentFolderId.value }}" } }.

Note that Retool's REST API resource may have limitations with multipart file upload. If the standard form data approach doesn't work with the Box upload endpoint, consider routing large file uploads through a Retool Workflow that handles the multipart upload, or use Box's chunked upload API for files over 50 MB.

For file download: Box does not provide direct download links from the metadata API. You need to call the file download endpoint which redirects to a temporary signed download URL. Create a query named getDownloadUrl. Set Method to GET. Set URL Path to /2.0/files/{{ table1.selectedRow.data.id }}/content. In the Advanced settings, set Follow Redirects to false. The response's Location header contains the actual download URL. Extract it from the response headers in a transformer.

Alternatively, use Box's shared link API to generate a temporary shared link with a download URL: POST /2.0/files/{{ fileId }}/shared_links with the shared_link settings in the body. This gives a clean download URL that can be displayed in the UI or used to trigger a browser download.

```
// uploadToBox query configuration
// Method: POST
// URL: https://upload.box.com/api/2.0/files/content
// Body Type: Form Data
// Form fields:
// Field 1: attributes (Text)
JSON.stringify({
  "name": "{{ filePicker1.value[0]?.name }}",
  "parent": { "id": "{{ currentFolderId.value || '0' }}" }
})
// Field 2: file (File)
// Value: {{ filePicker1.value[0] }}

// getSharedLink query — generate a download URL for a Box file
// Method: PUT
// URL Path: /2.0/files/{{ table1.selectedRow.data.id }}
// Body (JSON):
{
  "shared_link": {
    "access": "company",
    "permissions": {
      "can_download": true,
      "can_preview": true
    }
  }
}
// Response: file object with shared_link.download_url field
```

**Expected result:** The FilePicker component allows selecting a file. Clicking Upload sends the file to Box and the folder refreshes to show the new file. Clicking Download on a file row generates a Box shared link and opens the download URL in a new tab.

### 5. Implement Box search and permission management

Box's search API enables full-text search across all accessible content, filtering by file type, created date, metadata template, and folder scope. This is powerful for document management panels where users need to find files by content or metadata rather than browsing folder hierarchies.

Create a query named searchBox. Set Method to GET. Set URL Path to /2.0/search. Add URL Parameters:
- query: {{ searchInput.value }}
- type: file (or folder if needed)
- limit: {{ pageSize }}
- offset: {{ pageOffset }}
- ancestor_folder_ids: {{ rootFolderId }} (optional: restrict search to a specific folder tree)
- file_extensions: pdf,docx,xlsx (optional: filter by file type)
- content_types: name,description,file_content for full-text search

Apply a transformer to the search response that reshapes the entries array similarly to the folder contents transformer, adding a path field showing the file's full folder path for context.

For permission management: Box uses Collaborations to grant users access to files and folders. Create a query to list collaborations on a folder: GET /2.0/folders/{{ selectedFolderId }}/collaborations, which returns an array of collaboration objects with the user/group and their access role. Display this in a secondary Table component showing who has access to the selected folder. Add actions to add new collaborators (POST /2.0/collaborations) and remove existing ones (DELETE /2.0/collaborations/{{ collaborationId }}).

For complex integrations combining Box document management with internal workflow databases, approval systems, and notification services across multiple Retool apps, RapidDev's team can help architect and build your complete solution.

```
// searchBox query transformer
const entries = data?.entries || [];
const totalCount = data?.total_count || 0;

const results = entries.map(item => ({
  id: item.id,
  name: item.name,
  type: item.type,
  size: item.size ? `${(item.size / 1024).toFixed(1)} KB` : '—',
  modifiedAt: item.modified_at
    ? new Date(item.modified_at).toLocaleDateString()
    : '—',
  path: item.path_collection?.entries
    ?.slice(1) // remove root All Files entry
    ?.map(p => p.name)
    ?.join(' / ') || '',
  description: item.description || '',
  ownedBy: item.owned_by?.name || ''
}));

return { results, totalCount };
```

**Expected result:** The search query returns matching Box files and folders across the accessible content, with path information showing where each file lives. The collaboration panel shows who has access to selected folders, with functional add/remove collaborator actions.

## Best practices

- Store Box JWT credentials (private key, client ID, client secret) in Retool Configuration Variables as secrets rather than in resource settings directly — this prevents credential exposure in Retool's resource configuration UI.
- Build a folder ID reference table (JSON object or small database table) mapping human-readable folder names to Box folder IDs so queries remain readable and maintainable when Box content is reorganized.
- Use Box's metadata templates to attach structured metadata to files, and filter searches by metadata fields in Retool — this creates far more powerful document management than relying on folder structure and file naming conventions alone.
- Implement Box's chunked upload API for any workflow that regularly handles files larger than 20 MB, rather than using the single-file upload endpoint which can time out on large files over slow connections.
- Add error handling for Box's rate limits (10 API calls per second per user for most endpoints) by implementing retry logic in Retool Workflows for batch operations that process many Box items.
- When building permission management UIs, always verify the current collaboration state before making changes — use a getCollaborations query to display existing permissions before adding or removing collaborators, to avoid accidentally overwriting intentional access configurations.
- For Box content in regulated environments (HIPAA, FedRAMP, FINRA), ensure your Box account is on the appropriate compliance tier and that the service account used by Retool is documented in your compliance audit trail.

## Use cases

### Build an enterprise document review and management panel

Create a Retool app that browses Box folder hierarchies by client or project, displays file lists with metadata (name, size, modified date, modified by), allows uploading new documents to specific Box folders, and generates download links for files. Support staff can access and manage Box content through this panel without needing Box accounts or training.

Prompt example:

```
Build a Box document management panel with a folder browser showing a tree view of Box folder structure starting from a root folder. When a folder is selected, show a Table of files with name, size, last modified, and modified_by. Include an Upload button that opens a file picker and uploads to the selected folder. Add a Download button per row that generates a download URL for the selected file.
```

### Create a contract management dashboard with metadata and expiration tracking

Build a Retool dashboard that searches Box for contracts using Box's search API with metadata filters. Display contracts in a Table with custom metadata fields (contract type, counterparty, effective date, expiration date). Add status indicators for contracts expiring within 30 days, a detail panel showing full metadata, and actions for updating Box metadata fields and moving files to an 'Archived' folder.

Prompt example:

```
Build a contract management dashboard that searches Box for files with the metadata template 'contract' and displays contract_type, counterparty, effective_date, and expiration_date fields in a Table. Highlight rows where expiration_date is within 30 days in yellow and within 7 days in red. Include an Update Metadata action for editing contract fields and a Move to Archive action that calls the Box move item API to transfer the file to folder ID '987654321'.
```

### Build a document approval workflow panel

Create a Retool app that surfaces documents pending approval from a specific Box folder, shows document previews via Box's embedded viewer URL, and allows reviewers to approve (move to approved folder) or reject (move to rejected folder and add a comment) documents. Log all approval decisions to a Retool Database table for audit trail.

Prompt example:

```
Build a document approval panel that lists all files in Box folder '12345678' (Pending Review). For each file, show the filename, uploaded by, upload date, and file type. Include an Approve button that calls the Box copy or move API to move the file to folder '23456789' (Approved), a Reject button that prompts for a rejection reason, posts a comment on the Box item, and moves it to folder '34567890' (Rejected). Log each decision to a PostgreSQL audit_log table.
```

## Troubleshooting

### Box API returns 401 Unauthorized: 'The access token provided in the request is invalid'

Cause: The Box Developer Token has expired (they expire every 60 minutes), or the JWT access token was not refreshed before the API call. Box access tokens from JWT authentication also have a short lifespan (typically 60 minutes).

Solution: For Developer Tokens: regenerate the token in the Box Developer Console and update the Retool Configuration Variable. For JWT authentication in production: implement token caching and refresh in your token generator service — store the access token with its expiry time and request a new one only when it's expired or within 5 minutes of expiring. Implement Retool's Custom Auth automatic token refresh to re-authenticate on any 401 response.

### API returns 403 Forbidden when accessing files or folders that exist in Box

Cause: The Box JWT service account does not have collaborator access to the folder or file. Box's permission model requires explicit collaboration grants — even an admin service account cannot access content it hasn't been added as a collaborator on.

Solution: In Box's web interface, navigate to the folder the service account needs to access. Click Share → Invite Collaborators → enter the service account's email address (visible in Box Admin Console under Users → Service Accounts). Grant it at minimum 'Editor' access for read/write operations, or 'Viewer' for read-only. Repeat this for each root folder in your folder hierarchy — collaborator access is inherited by sub-folders.

### File upload fails with 'Request Entity Too Large' or upload query times out

Cause: The file exceeds Box's maximum file size for standard upload (50 MB), or Retool's query timeout is too short for the upload duration. Large files require Box's chunked upload API.

Solution: For files under 50 MB: increase the Retool query timeout in the resource's Advanced settings (set to 120000 ms = 2 minutes for large files). For files over 50 MB: implement Box's chunked upload API which splits the file into parts. This requires creating an upload session, uploading parts in sequence, and committing the session — best implemented as a Retool Workflow due to its multi-step nature.

### Box search returns no results even though files matching the query exist

Cause: Box's search index has a propagation delay of up to 10 minutes after file upload or modification before new content appears in search results. Additionally, the search may be scoped to a folder tree that doesn't include the files in question.

Solution: Wait up to 10 minutes after uploading or modifying files before expecting them to appear in search results — this is a Box platform constraint. Verify that the ancestor_folder_ids parameter in your search query includes a parent folder of the files you're looking for, or remove this parameter to search across all accessible content. Ensure the service account has collaborator access to the folders containing the target files.

## Frequently asked questions

### What is the difference between Box JWT authentication and standard OAuth 2.0 for Retool?

Box's JWT (server-to-server) authentication allows Retool to access Box as a service account without any individual user needing to authorize Box through a browser OAuth flow. This is the right choice for Retool internal tools where you want all users to access Box content through a shared service account. Standard OAuth 2.0 (user authentication) would require each Retool user to individually authorize Box — appropriate when you need per-user Box access with individual audit trails, but more complex to set up in Retool.

### Does Retool have a native Box connector?

No. As of 2026, Retool does not include Box in its native connector catalog. You must connect using Retool's generic REST API Resource type with Box's OAuth JWT authentication, as described in this guide. Unlike native connectors that provide action dropdowns and simplified authentication, the REST API Resource requires manually configuring each API endpoint path and response handling.

### Can Retool display Box document previews inline?

Yes, using Box's embed preview URL. Box provides a preview URL for most file types (PDF, Word, PowerPoint, images, video) that can be embedded in an iframe. In Retool, use the Custom Component or HTML component to embed Box's preview URL: https://app.box.com/file/{fileId}. Note that the embedded preview requires the viewing user to have an active Box session. For unauthenticated previews, generate a Box shared link with preview permissions and embed that URL instead.

### How does Retool handle Box's 10 API requests per second rate limit?

For interactive Retool dashboards with user-triggered queries, the 10 requests per second limit is rarely a concern — users don't make dozens of API calls per second. The limit becomes relevant in Retool Workflows that batch-process Box items in a Loop block. Implement a Wait block of 200ms between iterations in high-volume workflow loops to stay under the rate limit. For the Management API (admin operations), Box's rate limit is lower — check Box's documentation for specific endpoint limits.

### Can I use Retool to connect to Box Shield or Box Governance features?

Box Shield (data loss prevention, anomaly detection) and Box Governance (retention policies, legal holds) are managed through the Box Admin Console and their own APIs — separate from the Box Content API that Retool uses for file operations. You can call Box's Admin API endpoints for governance operations from Retool using the same REST API Resource, as long as the JWT service account has the required admin scopes. However, Box Shield alerts and governance workflows are better managed in Box's own interfaces or through Box's native webhook and event stream systems.

---

Source: https://www.rapidevelopers.com/retool-integrations/box
© RapidDev — https://www.rapidevelopers.com/retool-integrations/box