Box

​

Overview

​

Setup

1. In the Box Developer Console, create a Platform App (Custom App) with Server Authentication (Client Credentials Grant). JWT server authentication works the same way, but the broker then needs a signed JWT assertion for each token request.
2. Under App Access Level, keep App Access Only (the app works as its own service account) or pick App + Enterprise Access if it must act as a managed user. Under Application Scopes, enable Read all files and folders stored in Box and Write all files and folders stored in Box (root_readwrite), Manage webhooks (manage_webhook) for the webhook events, and Manage enterprise properties (manage_enterprise_properties) only if the broker reads enterprise metadata templates.
3. Authorize the app in the Box Admin Console (free developer accounts authorize it automatically) and reauthorize it after every scope change.
4. Note the Client ID and Client Secret (Configuration tab) and the Enterprise ID (General Settings). Keep them in broker secrets, for example BOX_CLIENT_ID, BOX_CLIENT_SECRET and BOX_ENTERPRISE_ID, and the current token in BOX_ACCESS_TOKEN. Inject them in a LoT action with GET SECRET.
5. The service account has its own, empty root folder. Invite it (its login looks like AutomationUser_…@boxdevedition.com, returned by UserMe) as an Editor collaborator on the plant folders the broker should use, and use those folder ids in payloads.

​

Authentication

{"access_token": "YOUR_BOX_ACCESS_TOKEN"}

{"form": "grant_type=client_credentials&client_id=<BOX_CLIENT_ID>&client_secret=<BOX_CLIENT_SECRET>&box_subject_type=enterprise&box_subject_id=<BOX_ENTERPRISE_ID>"}

​

Payloads

​

Uploading files

--CorefluxBoxBoundary
Content-Disposition: form-data; name="attributes"

{"name":"2026-10-05-shift-A.json","parent":{"id":"1001"}}
--CorefluxBoxBoundary
Content-Disposition: form-data; name="file"; filename="2026-10-05-shift-A.json"
Content-Type: application/json

{"line":"2","shift":"A","oee":0.87,"scrap":14}
--CorefluxBoxBoundary--

{"access_token": "<token>", "multipart": "--CorefluxBoxBoundary\r\nContent-Disposition: form-data; name=\"attributes\"\r\n\r\n{\"name\":\"2026-10-05-shift-A.json\",\"parent\":{\"id\":\"1001\"}}\r\n--CorefluxBoxBoundary\r\nContent-Disposition: form-data; name=\"file\"; filename=\"2026-10-05-shift-A.json\"\r\nContent-Type: application/json\r\n\r\n{\"line\":\"2\",\"shift\":\"A\",\"oee\":0.87,\"scrap\":14,\"operator\":\"Jo\\u00e3o\"}\r\n--CorefluxBoxBoundary--\r\n"}

​

Examples

{"access_token": "<token>", "folder_id": "1001", "query": "fields=id,type,name,size,modified_at&limit=100"}

{"access_token": "<token>", "file_id": "2001", "query": ""}

{"access_token": "<token>", "file_id": "2001", "scope": "enterprise", "template_key": "batchRecord", "body": {"line": "2", "batch": "1005-A", "product": "PX-200", "qualityState": "pending"}}

{"access_token": "<token>", "file_id": "2001", "scope": "enterprise", "template_key": "batchRecord", "body": [{"op": "test", "path": "/qualityState", "value": "pending"}, {"op": "replace", "path": "/qualityState", "value": "released"}]}

{"access_token": "<token>", "body": {"from": "enterprise_12345.batchRecord", "ancestor_folder_id": "1001", "query": "line = :line AND qualityState = :state", "query_params": {"line": "2", "state": "released"}, "fields": ["name", "metadata.enterprise_12345.batchRecord.batch"], "limit": 100}}

{"access_token": "<token>", "file_id": "2001", "body": {"parent": {"id": "1009"}, "name": "2026-10-05-shift-A.json", "tags": ["processed"]}}

{"access_token": "<token>", "file_id": "2001", "body": {"shared_link": {"access": "company", "permissions": {"can_download": true}}}}

{"access_token": "<token>", "body": {"target": {"id": "1006", "type": "folder"}, "address": "https://broker.example.com/box/webhooks", "triggers": ["FILE.UPLOADED", "FILE.MOVED"]}}

1. Get the current position: {"access_token": "<token>", "query": "stream_position=now"} returns next_stream_position and no events.
2. Ask for changes since then: {"access_token": "<token>", "query": "stream_type=changes&stream_position=<next_stream_position>&limit=100"}. Store the new next_stream_position after every call. Box may return an event more than once or out of order, so de-duplicate by event_id.

​

Events

​

Limits

• Box allows about 1000 API requests per minute and 240 upload requests per minute per user, and 6 searches per second (60 per minute) per user. Above the limit it answers 429 with a retry-after header. Wait that long before you retry.
• Direct uploads accept files up to 50 MB. Larger files need chunked upload sessions, which are not packaged.
• FolderItemsList returns at most 1000 entries per page (use usemarker=true and marker), Search at most 200, EventsList at most 500.
• One webhook per item and app, at most 1000 webhooks per app and user, HTTPS on port 443 only.
• File versions are tracked on paid accounts only. Recent items cover the last 90 days or 1000 items.
• Box indexes new and changed files with a delay, so Search may not find a file that was just uploaded. MetadataQuery and FolderItemsList see it right away.

​

Not packaged

• Delete events on purpose: files, folders, trash (permanent delete), file versions, metadata instances, shared link removal, collaborations, comments, tasks and webhooks. Archive files with FileUpdate or FolderUpdate (move) instead.
• Chunked upload sessions for files over 50 MB, the upload preflight check (OPTIONS /2.0/files/content), thumbnails, zip downloads and the long-poll real-time server (OPTIONS /2.0/events).
• The As-User header (act on behalf of another user from an admin token); request a user token with box_subject_type=user instead. The If-Match / If-None-Match headers and the content-md5 upload header.
• Collaboration create and update (granting access), users and groups administration, legal holds, retention, Shield, Sign, Box AI, Hubs, Doc Gen and enterprise events (admin_logs).
• The webhook receiver. A receiver would be a separate ENABLE_SERVER REST_API connector on a public HTTPS address that checks BOX-SIGNATURE-PRIMARY / BOX-SIGNATURE-SECONDARY (HMAC-SHA256 of the body plus BOX-DELIVERY-TIMESTAMP with the app’s signature keys) and rejects old timestamps. EventsList covers the same need without a public endpoint.

​

Suggested branches