Box

Required Scopes

To configure a Sync for Box, you need to request the following scopes from your Box OAuth application:

• root_readonly

Learn more about configuring scopes for your app in Adding Integrations.

Synced Objects

Box supports the following Synced Objects:

• Files
• Permissions

Files

Send a request to Enable Sync to start a file sync.

Syncs for Box can be created with one of the following configurations:

• Global Sync: All files in the user’s Box account will be synced.
• Folder Sync: Only files in the specified folder will be synced (recursively including all subfolders by default).
• Sync of specific files: Only a group of specific files will be synced.

Global Sync

Example

{
    "integration": "box",
    "pipeline": "files",
    "configuration": {}
}

Configuration options:

mimeTypes · string[]

An optional array of MIME types to filter synced files. Only files matching the specified MIME types will be synced.

fileNamePattern · string

An optional RE2 regular expression that filters synced files by filename. Only files whose name matches the pattern are synced. Folders are always traversed regardless of the pattern.

Matching is unanchored and case-sensitive. Use the inline (?i) flag for case-insensitive matches, and anchors (^, $) for exact-name matches. Lookarounds and backreferences are not supported. Patterns are limited to 1000 characters.

Example: (?i)\.pdf$ syncs only PDF files.

Folder Sync

Example

{
    "integration": "box",
    "pipeline": "files",
    "configuration": {
        "folderId": "1234567890"
    }
}

Configuration options:

folderId · string · required

A Box Folder ID to limit the Sync scope to.

shallowSync · boolean

Set to true to sync only the direct children of the specified folder, without recursing into subfolders. Defaults to false.

mimeTypes · string[]

An optional array of MIME types to filter synced files. Only files matching the specified MIME types will be synced.

fileNamePattern · string

An optional RE2 regular expression that filters synced files by filename. Only files whose name matches the pattern are synced. Folders are always traversed regardless of the pattern.

Matching is unanchored and case-sensitive. Use the inline (?i) flag for case-insensitive matches, and anchors (^, $) for exact-name matches. Lookarounds and backreferences are not supported. Patterns are limited to 1000 characters.

Example: (?i)\.pdf$ syncs only PDF files.

Sync of specific files

Example

{
    "integration": "box",
    "pipeline": "files",
    "configuration": {
        "fileIds": ["1234567890"]
    }
}

Configuration options:

fileIds · string[] · required

A list of Box File IDs to limit the Sync scope to. Up to 300 files can be watched from a single Sync using this option.

mimeTypes · string[]

An optional array of MIME types to filter synced files. Only files matching the specified MIME types will be synced.

fileNamePattern · string

An optional RE2 regular expression that filters synced files by filename. Only files whose name matches the pattern are synced. Folders are always traversed regardless of the pattern.

Matching is unanchored and case-sensitive. Use the inline (?i) flag for case-insensitive matches, and anchors (^, $) for exact-name matches. Lookarounds and backreferences are not supported. Patterns are limited to 1000 characters.

Example: (?i)\.pdf$ syncs only PDF files.

Choosing Files and Folders

You can allow your user to select files from their Box account in your app with the Box File Picker provided by the Paragon SDK.

Showing the File Picker

Use the Paragon SDK in your frontend application to show the File Picker in your app.

The SDK provides an ExternalFilePicker class to load Box’s JavaScript into your page and authenticate with your user’s connected Box account.

let picker = new paragon.ExternalFilePicker("box", {
    onFileSelect: (files) => {
        // Handle file selection
    },

    // Optional settings:
    integrationOptions: {
        box: {
            // If true, renders the Box picker UI inside an iframe to isolate
            // its styles from your application. Use this option if you experience
            // style conflicts between the Box picker and your app's CSS.
            scopeCSS: true
        }
    }
});

// Loads external dependencies and user's access token, and sets the folderId to the root folder
await picker.init({ folderId: "0" });

// Open the File Picker
picker.open();

You can configure the File Picker to listen for additional callbacks or to restrict allowed file types. Learn more about configuring File Picker options in the SDK Reference.