Box

What your agents can doCopy Anchor Link

Agents call Box API 2.0 with the connected account's credentials. Access depends on the app's scopes and the account's permissions and Box plan.

• Search files and folders by name and content, read or download files, and download folders as zip archives
• Upload files and new file versions to a folder
• Comment on files, reply to comments, and assign tasks
• Create shared links and manage collaborators
• Create folders, and rename, copy, and move files and folders
• Send Box Sign requests, ask Box AI about files, and add or change metadata
• Work with Box Hubs, Doc Gen, Archives, Shield lists, and Box Automate

The agent's API tool reaches api.box.com, the upload host upload.box.com, and the zip download host dl.boxcloud.com. It sends or receives files up to 16 MB in one call.

AuthenticationCopy Anchor Link

Both methods use a Platform App that you create in the Box Developer Console. Any Box account with access to the Developer Console can create one, including a free developer account. Helios doesn't ask for scopes with either method. Box gives the token every scope selected on the app, so the app's scopes decide what agents can do. Select the scopes your agents need on the app's Configuration tab under Application Scopes:

• An admin or co-admin: with a User app, these scopes only work for an admin or co-admin who approves the app. With a Server app, set App Access Level to App + Enterprise Access.
• A support request: Box adds Legal Holds and Global Content Manager to an app only after you ask its support team, and only on a paid plan. Ask for Global Content Manager only if you need it. Box warns that it changes how other calls behave, and writes then need the as-user header.

See Integration authentication for how credentials are stored and injected.

Box Client Credentials GrantCopy Anchor Link

Box shows the client secret only to accounts with multi-factor authentication turned on.

1. In the Developer Console, select New App, then Server. If Box shows Select Method, leave Client Credentials Grant selected. Select Create.

2. On the Configuration tab, select the scopes above. To act as a managed user instead of the app's service account, or to use the admin scopes, set App Access Level to App + Enterprise Access. To act as a managed user, also turn on Generate User Access Tokens. Save the changes.

3. Authorize the app:

   • Free developer account: Box authorizes the app when you create it.
   • Enterprise admin or co-admin: authorize it from the Configuration tab.
   • Other enterprise users: the Configuration tab asks you to submit the app for approval. Your admin gets an email.

   Box needs the app authorized again after any change to its scopes or access level.

4. Find your enterprise ID. Select your account icon at the top right of the Developer Console and choose Copy Enterprise ID.

5. In Helios, choose Box Client Credentials Grant. Enter the Client ID and Client Secret from the Configuration tab, and the Enterprise ID.

6. Optional: to act as a managed user, enter their ID in User ID. Leave it empty to act as the service account. A user finds their own ID under Account Settings → Account → Account Details as the Account ID.

7. Optional: for triggers, fill in Folder ID and Primary Signature Key. See Triggers.

8. Save.

Helios gets a new access token from Box when the old one expires, so there is nothing to renew. Helios keeps each token for up to an hour, so a scope change can take that long to apply. If you change the client secret in Box, enter the new one in Helios through Manage.

The service account starts with no files. To let agents work in a folder, invite the service account's email address, shown on the app's App Details tab, as a collaborator on that folder.

Your own Box OAuth appCopy Anchor Link

1. In the Developer Console, select New App, then User, and select Create.

2. On the Configuration tab, add this URL under OAuth 2.0 Redirect URI, select the scopes above, and save the changes:

   Copy Text

   https://api.heliosapp.com/integrations/box/oauth_callback

3. In an enterprise, an admin may need to enable the app first. Submit it from the app's Enablement tab, which emails your primary admin.

4. In Helios, choose Your own Box OAuth app. Enter the Client ID and Client Secret from the Configuration tab.

5. Optional: for triggers, fill in Folder ID and Primary Signature Key now. See Triggers.

6. Save, then approve access in Box.

Box replaces the refresh token each time Helios uses it, and a refresh token expires after 60 days. Helios refreshes the token every week, so an idle connection stays signed in.

If you change the client secret in Box, enter the new one through Manage. After you change the secret or the app's scopes, click Re-connect on the connection and approve again.

TriggersCopy Anchor Link

Box can start a Workflow when something happens in one folder and its subfolders. Helios registers a Box webhook on that folder for every event below when you save the connection, using the Manage webhooks scope. When you delete the connection, Helios attempts to remove the webhook. If removal fails, the connection is still deleted. Open the app's Webhooks tab in the Box Developer Console, find the webhook whose address ends with the deleted connection's ID, and delete that webhook. To turn triggers on, set these on the connection:

• Folder ID: the folder to watch. It is the number at the end of the folder's URL, such as 123456789 in https://app.box.com/folder/123456789. Box doesn't allow webhooks on the root folder (All Files). Leave the field empty to turn triggers off.
• Primary Signature Key, and optionally the Secondary Signature Key: on the app's Webhooks tab, click Manage signature keys, then Generate Key.

Watch a folder that the connected user owns. Box only lists webhooks on items that the user owns, and Helios needs that list to find and replace its webhook. With the service account, watch a folder the service account created, or set User ID and watch a folder that user owns.

All filters are optional patterns, and they are case-sensitive. *.pdf matches report.pdf but not REPORT.PDF. Use *.{pdf,PDF} to match both.

• File name, Folder name, and File or folder name match the item's name, not its path. For collaborations, the folder is the one being shared. For tasks, the file is the one the task is on. For Box Sign events, the file is the PDF that Box Sign makes from the document. Box sends no name for trashed or deleted items, and only the item's ID for comments and shared links, so those events have no name filter.
• Role matches the collaborator's role, such as editor, viewer, or co-owner. For collaboration.updated, it matches the new role.
• Link access matches who can open the link: open (anyone with the link), company, or collaborators.

The sign_request events need Box Sign, which Box offers on Business plans and higher.

If Box refuses one of the events when Helios registers the webhook, Helios registers the others. The trigger picker then shows the refused event as unavailable, with the reason. Helios doesn't ask Box again on its own. After you change the app's scopes or your Box plan, save the connection again. When Folder ID is empty, every event shows as unavailable.

Helios accepts a delivery when either signature matches, and rejects deliveries more than ten minutes old. To rotate keys, change one key at a time, in Box and in Helios.

Box retries a failed delivery up to 5 times over an hour. It deletes a webhook when the app is deleted or when all of the webhook's access tokens are revoked. It also deletes a webhook whose last successful delivery was 30 days ago, if more than 14 days passed between that delivery and the latest event. Only these deletions send webhook.deleted. Deleting the watched folder for good also removes the webhook, without that event. Save the connection again to register the webhook again.

Check that it worksCopy Anchor Link

• The connection: after you save, the connection's status shows Connected. Error means Box rejected the credentials. See Common errors.
• The webhook: if you own the watched folder, the app's Webhooks tab in the Developer Console lists a webhook whose address ends with the connection's ID.
• A trigger:
  1. Add file.uploaded to a workflow with no filters.
  2. Upload a file to the watched folder.
  3. Check that a run starts. Then open the connection in Helios and click Webhook events to see the event.

Common errorsCopy Anchor Link