How to Integrate Retool with Box

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.

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.

1// Box JWT Token Generator — deploy as a Retool Workflow or serverless function
2// This generates a Box access token using JWT authentication
3// Called by Retool's Custom Auth step
4
5// Required: Box JWT configuration values as environment variables
6// BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_ENTERPRISE_ID, BOX_PRIVATE_KEY, BOX_KEY_ID, BOX_PASSPHRASE
7
8const jwt = require('jsonwebtoken');
9const axios = require('axios');
10
11async function getBoxToken() {
12  const privateKey = process.env.BOX_PRIVATE_KEY.replace(/\\n/g, '\n');
13  
14  const jwtClaims = {
15    iss: process.env.BOX_CLIENT_ID,
16    sub: process.env.BOX_ENTERPRISE_ID,
17    box_sub_type: 'enterprise',
18    aud: 'https://api.box.com/oauth2/token',
19    jti: require('crypto').randomBytes(16).toString('hex'),
20    exp: Math.floor(Date.now() / 1000) + 30
21  };
22  
23  const assertion = jwt.sign(jwtClaims, {
24    key: privateKey,
25    passphrase: process.env.BOX_PASSPHRASE || ''
26  }, {
27    algorithm: 'RS256',
28    keyid: process.env.BOX_KEY_ID
29  });
30  
31  const response = await axios.post('https://api.box.com/oauth2/token', {
32    grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
33    assertion,
34    client_id: process.env.BOX_CLIENT_ID,
35    client_secret: process.env.BOX_CLIENT_SECRET
36  });
37  
38  return response.data.access_token;
39}

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.

1// getFolderContents transformer
2// Input: data (Box folder items response)
3const entries = data?.entries || [];
4
5return entries.map(item => ({
6  id: item.id,
7  name: item.name,
8  type: item.type, // 'file' or 'folder'
9  extension: item.type === 'file' ? item.name.split('.').pop()?.toLowerCase() : null,
10  size: item.type === 'file' && item.size
11    ? item.size < 1024 ? `${item.size} B`
12    : item.size < 1048576 ? `${(item.size / 1024).toFixed(1)} KB`
13    : `${(item.size / 1048576).toFixed(2)} MB`
14    : '—',
15  modifiedAt: item.modified_at
16    ? new Date(item.modified_at).toLocaleDateString('en-US', { year: 'numeric', month: 'short', day: 'numeric' })
17    : '—',
18  modifiedBy: item.modified_by?.name || '—',
19  status: item.item_status || 'active'
20}));

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.

1// uploadToBox query configuration
2// Method: POST
3// URL: https://upload.box.com/api/2.0/files/content
4// Body Type: Form Data
5// Form fields:
6// Field 1: attributes (Text)
7JSON.stringify({
8  "name": "{{ filePicker1.value[0]?.name }}",
9  "parent": { "id": "{{ currentFolderId.value || '0' }}" }
10})
11// Field 2: file (File)
12// Value: {{ filePicker1.value[0] }}
13
14// getSharedLink query — generate a download URL for a Box file
15// Method: PUT
16// URL Path: /2.0/files/{{ table1.selectedRow.data.id }}
17// Body (JSON):
18{
19  "shared_link": {
20    "access": "company",
21    "permissions": {
22      "can_download": true,
23      "can_preview": true
24    }
25  }
26}
27// Response: file object with shared_link.download_url field

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.

1// searchBox query transformer
2const entries = data?.entries || [];
3const totalCount = data?.total_count || 0;
4
5const results = entries.map(item => ({
6  id: item.id,
7  name: item.name,
8  type: item.type,
9  size: item.size ? `${(item.size / 1024).toFixed(1)} KB` : '—',
10  modifiedAt: item.modified_at
11    ? new Date(item.modified_at).toLocaleDateString()
12    : '—',
13  path: item.path_collection?.entries
14    ?.slice(1) // remove root All Files entry
15    ?.map(p => p.name)
16    ?.join(' / ') || '',
17  description: item.description || '',
18  ownedBy: item.owned_by?.name || ''
19}));
20
21return { results, totalCount };