Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Box

Scalekit connector
Open markdown

The Box connector lets your AI agent act in each user's Box account. Each user signs in to Box once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 102 tools.

Tools
102
What they doRead · write · destructive
49 · 35 · 1849 read35 write18 destructive
Users sign in with
OAuth app
Scalekit's or your own

What you can do

  • Manage files and folders: upload, copy, move, rename, trash, and restore files and folders
  • Search content: find files, folders, and web links, and list recent items and folder contents
  • Share and collaborate: grant user or group access, create shared links, and add comments on files
  • Ask Box AI: ask questions about files and extract structured data using metadata templates or prompts
  • Send for signature: create, track, and cancel Box Sign requests for one or more files
  • Assign tasks and apply metadata: create file tasks, assign them to users, and apply metadata to files

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Create the Box connection

    In AgentKit > Connections, create a Box connection. The name you give it is the connection_name your code passes. See Configure connections.

    Scalekit credentials are available for Box, so you don't need to register an OAuth app. To show your own app on the consent screen, use your own credentials instead.

    Use your own OAuth app

    Connect Box to Scalekit so your agent can manage files, folders, users, tasks, and more on behalf of your users. Box uses OAuth 2.0 — users authorize access through Box’s login flow, and Scalekit handles token storage and refresh automatically.

    You will need:

    • A Box developer account (free at developer.box.com)
    • Your Box OAuth app’s Client ID and Client Secret
    • The redirect URI from Scalekit to paste into Box

    1. Create a Box OAuth app

      • Go to the Box Developer Console and click Create New App.

      • Select Custom App as the app type.

      • Under authentication method, choose User Authentication (OAuth 2.0). This lets your agent act on behalf of each user who authorizes access.

      • Enter an app name (e.g. “My Agent App”) and click Create App.

    2. Copy the redirect URI from Scalekit

      • In Scalekit dashboard, go to AgentKit > Connections > Create Connection.
      • Find Box and click Create.
      • Click Use your own credentials and copy the redirect URI. It looks like: https://<env>.scalekit.cloud/sso/v1/oauth/<conn_id>/callback

    3. Add the redirect URI to Box

      • In the Box Developer Console, open your app and go to the Configuration tab.
      • Under OAuth 2.0 Redirect URI, paste the redirect URI from Scalekit and click Save Changes.

    4. Select scopes for your app

      Still on the Configuration tab in Box, scroll down to Application Scopes and enable the permissions your agent needs:

      ScopeRequired for
      root_readonlyReading files and folders
      root_readwriteCreating, updating, and deleting files/folders
      manage_groupsCreating and managing groups
      manage_webhookCreating and managing webhooks
      manage_managed_usersCreating and managing enterprise users
      manage_enterprise_propertiesAccessing enterprise events

      Click Save Changes after selecting scopes.

    5. Add credentials in Scalekit

      • In the Box Developer Console, open your app → Configuration tab.
      • Copy your Client ID and Client Secret.
      • In Scalekit dashboard, go to AgentKit > Connections, open the Box connection you created, and enter:
        • Client ID — from Box
        • Client Secret — from Box
        • Scopes — select the same scopes you enabled in Box (e.g. root_readonly, root_readwrite)

      • Click Save.

    6. Add a connected account for each user

      Each user who authorizes Box access becomes a connected account. During authorization, Box will show your app name and request the scopes you configured.

      Via dashboard (for testing)

      • In Scalekit dashboard, go to your Box connection → Connected Accounts → Add Account.
      • Enter a User ID (your internal identifier for this user, e.g. user_123).
      • Click Add — you will be redirected to Box’s OAuth consent screen to authorize.

      Via API (for production)

      In production, generate an authorization link and redirect your user to it:

      const { link } = await scalekit.actions.getAuthorizationLink({
        connectionName: 'box',
        identifier: 'user_123',
      });
      // Redirect your user to `link`

      After the user authorizes, Scalekit stores their tokens. Your agent can then call Box tools on their behalf without any further redirects.

  4. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENVIRONMENT_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'box'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Box:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'box_collections_list',
      toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user signs in once. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • box_ai_askSends a natural-language question plus up to 25 Box files as context to a supported LLM and returns an answer, optionally with citations and prior dialogue history for follow-up questions.Read-only

    AI Ask

    Sends a natural-language question plus up to 25 Box files as context to a supported LLM and returns an answer, optionally with citations and prior dialogue history for follow-up questions.

    Inputs

    itemsstringrequired
    JSON array of 1-25 Box files to use as context, each with a unique file ID. Example: [{"id": "12345", "type": "file"}]
    modestringrequired
    Whether the question is about a single item or multiple items. If 'single_item_qa', the items list must contain exactly one item.one of multiple_item_qasingle_item_qa
    promptstringrequired
    The question to ask about the given items. Max 10000 characters.
    dialogue_historystring
    JSON array of previous question/answer turns, to give the LLM conversational context for a follow-up question.
    include_citationsboolean
    Whether to include citations (the specific file passages the answer is based on) in the response.
  • box_ai_extractSends a freeform extraction prompt plus Box files to an LLM and returns extracted data as key-value pairs, without needing a predefined metadata template.Read-only

    AI Extract

    Sends a freeform extraction prompt plus Box files to an LLM and returns extracted data as key-value pairs, without needing a predefined metadata template. Use AI Extract Structured instead when you have a metadata template or a fixed field schema.

    Inputs

    itemsstringrequired
    JSON array of 1-25 Box files to extract data from, each with a unique file ID. Example: [{"id": "12345", "type": "file"}]
    promptstringrequired
    Instructions telling the LLM what data to extract, e.g. a list of fields to pull out. Can be plain text or an XML/JSON schema. Max 10000 characters.
  • box_ai_extract_structuredExtracts structured metadata from Box files using a metadata template or an explicit typed field list, returning key-value pairs matching that schema.Read-only

    AI Extract Structured

    Extracts structured metadata from Box files using a metadata template or an explicit typed field list, returning key-value pairs matching that schema. Provide either metadata_template_key (with metadata_template_scope) or fields, but not both.

    Inputs

    itemsstringrequired
    JSON array of 1-25 Box files to extract data from, each with a unique file ID. Example: [{"id": "12345", "type": "file"}]
    fieldsstring
    JSON array of field definitions to extract, used instead of a metadata template. Each field needs a unique 'key' and a 'type' (string, float, date, enum, or multiSelect). Mutually exclusive with metadata_template_key.
    include_confidence_scoreboolean
    Whether to include a confidence score for each extracted field in the response.
    metadata_template_keystring
    The key of an existing Box metadata template to extract fields for. Provide metadata_template_scope alongside this. Mutually exclusive with 'fields'.
    metadata_template_scopestring
    The scope of the metadata template: 'global' or an enterprise scope like 'enterprise_12345'. Required when metadata_template_key is set.
  • box_collaboration_getRetrieves details of a specific collaboration.Read-only

    Get Collaboration

    Retrieves details of a specific collaboration.

    Inputs

    collaboration_idstringrequired
    ID of the collaboration.
    fieldsstring
    Comma-separated list of fields to return.
  • box_collection_items_listRetrieves the items in a collection (e.g.Read-only

    List Collection Items

    Retrieves the items in a collection (e.g. Favorites).

    Inputs

    collection_idstringrequired
    ID of the collection.
    fieldsstring
    Comma-separated list of fields to return.
    limitinteger
    Max results.
    offsetinteger
    Pagination offset.
  • box_collections_listRetrieves all collections (e.g.Read-only

    List Collections

    Retrieves all collections (e.g. Favorites) for the user.

    Inputs

    fieldsstring
    Comma-separated list of fields to return.
    limitinteger
    Max results.
    offsetinteger
    Pagination offset.
  • box_comment_getRetrieves a comment.Read-only

    Get Comment

    Retrieves a comment.

    Inputs

    comment_idstringrequired
    ID of the comment.
    fieldsstring
    Comma-separated list of fields to return.
  • box_events_listRetrieves events from the event stream.Read-only

    List Events

    Retrieves events from the event stream.

    Inputs

    created_afterstring
    Return events after this date (ISO 8601).
    created_beforestring
    Return events before this date (ISO 8601).
    event_typestring
    Comma-separated list of event types to filter.
    limitinteger
    Max events to return.
    stream_positionstring
    Pagination position from a previous response.
    stream_typestring
    Event stream type: all, changes, sync, or admin_logs.

Workflows

Proxy API call
// List files in the root folder
const result = await actions.request({
  connectionName: 'box',
  identifier: 'user_123',
  path: '/2.0/folders/0/items',
  method: 'GET',
});
console.log(result);
List folder contents

Start here to discover file and folder IDs. Use "0" for the root folder.

const result = await actions.executeTool({
  toolName: 'box_folder_items_list',
  connector: 'box',
  identifier: 'user_123',
  toolInput: {
    folder_id: '0',  // root folder
  },
});
// result.entries[] contains files and folders with their IDs
Get file details
const file = await actions.executeTool({
  toolName: 'box_file_get',
  connector: 'box',
  identifier: 'user_123',
  toolInput: { file_id: '12345678' },
});
Search Box
const results = await actions.executeTool({
  toolName: 'box_search',
  connector: 'box',
  identifier: 'user_123',
  toolInput: {
    query: 'quarterly report',
    type: 'file',
    file_extensions: 'pdf,docx',
  },
});
Create a task on a file
const task = await actions.executeTool({
  toolName: 'box_task_create',
  connector: 'box',
  identifier: 'user_123',
  toolInput: {
    file_id: '12345678',
    message: 'Please review this document',
    action: 'review',
    due_at: '2025-12-31T00:00:00Z',
  },
});
// task.id is the task ID — use it with box_task_assignment_create
Share a file
const link = await actions.executeTool({
  toolName: 'box_shared_link_file_create',
  connector: 'box',
  identifier: 'user_123',
  toolInput: {
    file_id: '12345678',
    access: 'company',   // open | company | collaborators
    can_download: true,
  },
});
Create a webhook

Webhooks require the manage_webhook scope. The triggers field is an array of event strings.

const webhook = await actions.executeTool({
  toolName: 'box_webhook_create',
  connector: 'box',
  identifier: 'user_123',
  toolInput: {
    target_id: '0',
    target_type: 'folder',
    address: 'https://your-app.com/webhooks/box',
    triggers: ['FILE.UPLOADED', 'FILE.DELETED', 'FOLDER.CREATED'],
  },
});
Add a collaborator to a folder

Collaborations grant a user or group access to a specific file or folder. You need the user’s Box ID or email login.

// First, get the user's Box ID using box_users_list or box_user_me_get
const collab = await actions.executeTool({
  toolName: 'box_collaboration_create',
  connector: 'box',
  identifier: 'user_123',
  toolInput: {
    item_id: 'FOLDER_ID',
    item_type: 'folder',
    accessible_by_id: 'USER_BOX_ID',
    accessible_by_type: 'user',
    role: 'editor',
  },
});
// To find the collaboration ID later, use box_folder_collaborations_list

Related: other Productivity connectors

All 144 in Productivity