C3 AI Documentation Home

Box Connector

The C3 Agentic AI Platform connector for Box connects C3 AI applications to your Box content and folders.

Configure authentication for the Box connector

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

  • JWT with a service account: recommended for automated, server-side integrations
  • OAuth 2.0 with access and refresh tokens: useful for user-based access and temporary credentials

Prerequisites

Before you configure authentication, make sure 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
  • The BoxAccount and BoxCredentials Types available in your C3 application model

Method 1: Authenticate with JWT (service account)

Use JWT with a service account for automated, server-side integrations.

Create a Box app

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

Configure the app

Set the access level and generate the key pair that the connector authenticates with:

  1. Open the settings page of your app.
  2. Set App Access Level to App + Enterprise Access.
  3. Under Advanced Features, enable Make API calls using the as-user header.
  4. Select Generate a Public/Private Keypair.
    • Box downloads a .json file that contains 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)

In this step, you create and securely store the credentials that authenticate with Box. You only register authentication material (client ID, keys, and enterprise or user identifiers) with the platform. This step does not configure a Box file system or make Box content accessible.

The next step configures the file system mount and paths.

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 file system and default mount

This step configures the Box FileSystem and defines how the environment exposes Box storage. The default mount maps file system paths to a specific Box drive. Applications and users then access Box content through standard file APIs. This step puts the Box credentials you created to use, and you need it before any read or write operation against Box.

Python

# Create a Box filesystem configuration with a default mount 

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

 
# Set the default Box mount

config.setMount("/", "box://CompanyBoxDrive/")

After you apply this configuration, you can access Box files through standard file system APIs.

Create a FileSourceSystem for Box

Create a Box-backed FileSourceSystem with metadata. The FileSourceSystem sets the logical drive name that references Box content, and it configures how file system paths resolve.

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

JSON
{
   "name": "MyBoxDrive",
   "rootUrlOverride": "box://CompanyBoxDrive/"

}

This metadata definition creates a FileSourceSystem named MyBoxDrive. The box:// scheme in rootUrlOverride makes Box the underlying storage. rootUrlOverride sets the root file system URL that resolves paths for Box-backed file operations.

Associate credentials with the FileSourceSystem

After you create the FileSourceSystem, associate it with the Box credentials you created.

Python

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

These credentials enable authenticated access to Box. The file system becomes available through the Box FileSystem and the default mount you configured earlier.

JWT authentication works only with Box Enterprise accounts.

Method 2: Authenticate with OAuth 2.0

Use OAuth 2.0 for user-based access and temporary credentials.

Create a Box app

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

Configure the app

Set the access level, scopes and redirect URI that the authorization step uses:

  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, such as https://<your-redirect-uri>.

Authorize the app

Generate the authorization URL:

Python

redirectURI = "https://<your-redirect-uri>" 
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. Box then redirects you to the configured redirect URI, with an authorization code 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 with metadata

Create or update the Box FileSourceSystem with one metadata definition. A FileSourceSystem defined in metadata gives you a consistent logical drive to reference across the application.

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

JSON
{
  "name": "MyBoxSystem",
  "rootUrlOverride": "box://CompanyBoxDrive/"
}

This metadata definition sets:

  • A single logical Box drive (MyBoxSystem)
  • Box as the storage, through the box:// scheme
  • Explicit path resolution through rootUrlOverride

The drive name (for example, CompanyBoxDrive) must match the name in the corresponding file system mount.

Retrieve the FileSourceSystem

After the metadata is persisted, retrieve the FileSourceSystem to attach credentials.

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

Attach the OAuth tokens to the credential object

Python

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

When the access token expires, the platform uses the refresh token to get new tokens and stores them with the credentials, so you exchange the authorization code only once. This API replaces all legacy Box credential configuration methods. Always associate credentials with a FileSourceSystem to keep file system behavior and configuration consistent.

Apply credentials to the FileSourceSystem

Python

fs.setCredentials(creds)

This call associates the Box credentials with the FileSourceSystem. It enables authenticated access through the configured file system and mounts.

Verify the Box connection

After you configure the Box FileSourceSystem and apply credentials, list files from the configured Box drive. A file list confirms that authentication, file system configuration, and mounts work.

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, the command returns the files and folders at the root of the Box drive.

Behavior summary

The platform picks the authentication method from the credentials you provide:

  • If you provide accessToken, the platform assumes OAuth 2.0.

  • If you do not provide accessToken, the platform assumes JWT, and you must fill in all JWT fields.

See also

Was this page helpful?