C3 AI Documentation Home

Box Connector

The C3 Agentic AI Platform connector for Box enables integration between C3 AI applications and your Box content and folders.

Configure Authentication for the Box Connector

You can authenticate with Box using one of the following methods, depending on your enterprise setup:

  • JWT with a Service Account – Recommended for automated, server-side integrations
  • OAuth 2.0 using access and refresh tokens – Useful for user-based access and temporary credentials

This topic walks you through both authentication methods.

Prerequisites

Before configuring authentication, ensure you have the following:

  • Access to the Box Developer Console
  • A Box Enterprise account (JWT authentication works only with enterprise accounts)
  • Access to C3 AI Studio
  • Availability of the BoxAccount and BoxCredentials types in your C3 application model

Method 1: Authenticate Using JWT (Service Account)

Create a Box App

  1. In the Box Developer Console, click Create New App.
  2. Select Server Authentication (client credentials grant).
  3. Provide a name and purpose for your app.
  4. Click Create App.

Configure the App

  1. Open your app’s settings page.
  2. Set App Access Level to App + Enterprise Access.
  3. Under Advanced Features, enable Make API calls using the as-user header.
  4. Click Generate a Public/Private Keypair.
    • This downloads a .json file containing the required credentials.
  5. Submit the app for admin approval (unless you are the admin).

Gather Required Fields

From the Box Developer Console and the downloaded .json file, collect the following:

  • Account ID (from Account Settings)
  • Client ID
  • Client Secret
  • Enterprise ID
  • Public Key ID
  • Private Key Password

Set Credentials in C3 (Create and Store Box Credentials)

This step focuses exclusively on creating and securely storing the credentials required to authenticate with Box. At this stage, you are only registering authentication material (client ID, keys, and enterprise or user identifiers) with the platform. Completing this step does not configure a Box filesystem or make Box content accessible.

The filesystem mount and path configuration are handled in a subsequent step.

Python
json_creds = {
    "type": "BoxCredentials",
    "accountId": "...",           # client ID
    "clientSecret": "...",        # client secret
    "accessKey": "...",           # public key ID
    "secretKey": "...",           # private key
    "privateKeyPassword": "...",  # key password
    "enterpriseId": "...",        # enterprise ID
    "userId": "...",              # your Box account ID
}

creds = c3.BoxCredentials.make(json_creds)

Configure the Box FileSystem and Default Mount

This step configures the Box FileSystem and defines how Box storage is exposed within the environment. By creating a default mount, you map filesystem paths to a specific Box drive, enabling applications and users to access Box content using standard file APIs. This step operationalizes the previously created Box credentials and is required before any read or write operations against Box can be performed.

Python

# Create a Box filesystem configuration with a default mount 

config = c3.FileSystem.box().config() 

 
# Apply the filesystem configuration at the environment level 

config.setMount("/", "TestBoxDrive")

After this configuration is applied, Box files can be accessed using standard filesystem APIs.

Create a FileSourceSystem for Box

Create a Box-backed FileSourceSystem using metadata. Defining the FileSourceSystem establishes the logical drive name that will be used to reference Box content and configures how filesystem paths are resolved.

To create a FileSourceSystem, create a JSON metadata file. For example, create BoxSourceSystem.json in the /metadata/FileSourceSystem directory:

JSON
{ 
   "name": "MyBoxDrive", 
   "provider": "Box", 
   "rootUrlOverride": "box://TestBoxDrive/" 

}

This metadata definition creates a FileSourceSystem named MyBoxDrive with Box as the underlying provider. The rootUrlOverride specifies the root filesystem URL that is used when resolving paths for Box-backed file operations.

Associate Credentials with the FileSourceSystem

After the FileSourceSystem is created, associate it with the previously created Box credentials.

Python

fsSystem = FileSourceSystem.forName("MyBoxDrive") 
fsSystem.setCredentials(creds)

Associating credentials enables authenticated access to Box but does not yet make the filesystem available for use. Filesystem availability is completed in the subsequent step when the Box FileSystem and default mount are configured.

Note:
JWT authentication works only with Box Enterprise accounts.

Method 2: Authenticate Using OAuth 2.0

Create a Box App

  1. In the Box Developer Console, click Create New App.
  2. Select User Authentication (OAuth 2.0).
  3. Name your app and click Create App.

Configure the App

  1. Set App Access Level to App + Enterprise Access.
  2. Under Advanced Features, enable the following:
    • Make API calls using the as-user header
    • Appropriate OAuth scopes (read/write access)
  3. Add a Redirect URI (for example, https://c3.ai).

Authorize the App

Generate the authorization URL:

Python

redirectURI = "https://c3.ai" 
clientId = "..."  # From Box Developer Console 
authURL = ( 

    "https://account.box.com/api/oauth2/authorize" 

    f"?client_id={clientId}" 

    f"&redirect_uri={redirectURI}" 

    "&response_type=code" 

) 

authURL

Visit the authorization URL and grant access. After successful authorization, you will be redirected to the configured redirect URI with an authorization code included in the URL.

Use the Authorization Code

Python
json_creds = {
    "type": "BoxCredentials",
    "accountId": "...",      # client ID
    "clientSecret": "...",   # client secret
}

creds = c3.BoxCredentials.make(json_creds)

auth_code = "..."  # From redirect URI
tokens = creds.acquireTokenFromAuthorizationCode(auth_code)

Configure FileSourceSystem Credentials (High-Level API)

FileSourceSystem is the single, supported entry point for configuring Box credentials.

Define and Persist the FileSourceSystem Using Metadata

Create (or update) the Box FileSourceSystem using a single, canonical metadata definition.
Defining the FileSourceSystem in metadata establishes a consistent logical drive that can be referenced across the application.

To create a FileSourceSystem, add a JSON file (for example, BoxSourceSystem.json) in the /metadata/FileSourceSystem directory:

JSON
{
  "name": "MyBoxSystem",
  "provider": "Box",
  "rootUrlOverride": "box://TestBoxDrive/"
}

This metadata definition establishes:

  • A single logical Box drive (MyBoxSystem)
  • The Box provider
  • Explicit path resolution via rootUrlOverride

The drive name (for example, TestBoxDrive) must match the name specified in the corresponding filesystem mount.

Retrieve the FileSourceSystem

After persistence, retrieve the FileSourceSystem for credential attachment.

Python
fs = c3.FileSourceSystem.forName("MyBoxSystem")

Attach the OAuth tokens to the credential object

Python

creds = creds.withAccessToken(tokens["accessToken"]).withRefreshToken(tokens["refreshToken"])

These tokens expire when the notebook is restarted. You’ll need to regenerate them each time. This API replaces all legacy Box credential configuration methods. Credentials must always be associated with a FileSourceSystem to ensure consistent filesystem behavior and configuration.

Apply credentials to the FileSourceSystem

Python

fs.setCredentials(creds)

This associates the Box credentials with the FileSourceSystem and enables authenticated access through the configured filesystem and mounts.

Verify the Box Connection

After configuring the Box FileSourceSystem and applying credentials, verify the connection by listing files from the configured Box drive. This confirms that authentication, filesystem configuration, and mounts are working as expected.

Run the following command to list files at the root of the Box drive:

Python

c3.FileSystem.box().listFiles()

If the connection is configured correctly, this command returns a list of files and folders accessible from the root of the Box drive.

Behavior Summary

  • If accessToken is provided → OAuth2.0 is assumed

  • If accessToken is not provided → JWT is assumed, and all JWT fields must be filled

See also

Was this page helpful?