Skip to main content
The Box connector indexes files that a Box service account or managed user can access. You can index everything visible to that identity or limit indexing to specific folders.

​
How it works

On each refresh, the connector recursively lists every folder in its configured scope, then downloads and processes only files and web links modified during the indexing window. For a large Box tree, select specific folders and choose a refresh frequency that fits your Box API capacity.

​
Before you begin

You need:
  • Access to the Box Developer Console
  • A Box Admin or Co-Admin who can authorize a server-authenticated Platform App
  • An Onyx administrator account
  • The email address of a Box managed user if you plan to index as that user
A regular Box Individual account does not provide the enterprise features required for this setup. Use a Box enterprise account, developer account, or developer sandbox.

​
Choose the Box content identity

The connector can access Box content in either of these ways: Folder ID 0 means the root folder of the selected content identity. It is not a global root containing every user’s private Box files.

​
Configure Box

1

Create a Platform App

In the Box Developer Console, select Platform Apps → New App. Create a Custom App that uses Server Authentication (Client Credentials Grant). Give it a recognizable name, such as Onyx Connector.
2

Set the access level and scopes

On the app’s Configuration tab, set App Access Level to App + Enterprise Access.Enable scopes according to the features you will use:
These scopes allow the app to call the required APIs. The selected service account or managed user still must be able to access each file and folder that you want Onyx to index.
3

Enable managed-user access

If you will enter a managed user’s email in Onyx, enable Generate user access tokens under the app’s advanced or additional configuration. You can leave this disabled when using only the app service account.
4

Save and authorize the app

Save the configuration. Authorize the app from the Developer Console, or submit it for authorization to a Box Admin or Co-Admin.An admin can also authorize it from Admin Console → Integrations → Platform Apps Manager → Server Authentication Apps by adding the app’s Client ID.
Box authorization captures the app configuration at that moment. If you later change its scopes or access level, an admin must reauthorize the app before the changes take effect.
5

Copy the credentials

From the app’s settings, copy the Client ID, Client Secret, and Enterprise ID.Box requires two-factor authentication on your account before it reveals the client secret. Treat the secret as sensitive and do not place it in source control.
For more detail on these Box settings, see Box’s Client Credentials Grant setup guide and Platform App approval guide.

​
Configure Onyx

1

Open the Box connector

In Onyx, go to Admin Panel → Add Connector and select Box.
2

Enter the Box credentials

Create a credential and enter the values copied from Box:
3

Choose the folders to index

Give the connector a name. In Folders, enter one or more Box folder IDs or full folder URLs, such as https://app.box.com/folder/123456789.Leave Folders empty to index everything visible from the selected identity’s root folder. Every configured folder is indexed recursively.
4

Choose indexing and access options

Under Advanced Configuration, enable Include Web Links if you want Box bookmarks indexed as lightweight documents.Select the connector access type:
  • Public makes all indexed Box content visible to every Onyx user.
  • Private limits the entire connector to selected Onyx users and groups.
  • Auto Sync Permissions mirrors supported Box access controls and is available on Onyx Cloud and Enterprise Edition.
5

Connect and verify

Select Connect. Then open Admin Panel → Existing Connectors, select the connector, and confirm its initial indexing attempt completes.

​
Auto Sync Permissions

With Auto Sync Permissions, Onyx maps accepted, read-capable Box collaborations to matching Onyx user emails and Box groups. It also handles inherited folder access and shared links:
  • A non-password-protected People with the link link is treated as public.
  • A People in your company link is available to synced users in the Box enterprise.
  • An upload-only collaboration does not grant read access in Onyx.
  • Box login emails must match the users’ email addresses in Onyx.
The Box app must have Manage users and Manage groups, and an admin must reauthorize the app after adding those scopes.
Review the access type before connecting. Choosing Public does not preserve Box permissions and can expose indexed content to every Onyx user.

​
Troubleshooting

Confirm that the Client ID, Client Secret, and Enterprise ID belong to the same Platform App. Verify that a Box Admin or Co-Admin authorized the app. If any app setting changed, reauthorize it in the Box Admin Console.
Enter the user’s exact Box login email. Confirm the user is managed by the same enterprise, App + Enterprise Access and Manage users are enabled, and Generate user access tokens is enabled. Reauthorize the app after correcting any setting.
Confirm the folder ID or URL and verify that the selected managed user can open the folder. If you left the user email blank, add the app service account as a collaborator on the folder. An empty service-account root does not include existing enterprise content automatically.
Confirm Manage users and Manage groups are enabled and the app was reauthorized afterward. Also confirm you are using Onyx Cloud or Enterprise Edition.
Each refresh walks the full configured folder tree, with folder contents listed in pages of up to 200 entries. Permission sync makes additional calls for folder and file collaborations, users, and groups. Limit Folders to the required subtrees or increase the refresh frequency for very large Box deployments.