API integration for Box
We build your Box connector
We wire Box into your business file: deliverable deposit, reaction to a file, sharing audit. Scoping up front, alerts in production.
- Senior product team
- DMS connectors in production
- from scoping to monitoring
What does the Box API provide and why connect Box to a business application?
Box is an enterprise document storage and management platform with built-in governance, retention and electronic signature capabilities. Its API lets your application deposit, read and organise files in Box, receive a notification whenever a document is added or modified, and manage access rights per folder. You connect Box when the DMS is already in place and governed, and you want the business application to automatically file documents into it without teams switching between tools.
What our clients build on the Box API
Project deliverables in the client folder
Deposit from the product, FILE.UPLOADED starts the review. Box IDs travel, not paths that get renamed.
HR: App User per employee
Documents in a personal folder, metadata template "document type". No named credentials that survive a departure.
Migration paced at 240 uploads/min
The quota that kills is not the general 1,000. Resume, failure log, not a naive parallel pool.
Sharing audit over one year
admin_logs for an incident or a DPO request. Webhooks, limited to one item, do not replace that trail.
What this changes in your Box DMS
Engineering in service of a measurable outcome: a business deposit, an audit trail, fewer production surprises.
Box stays the DMS, the product attaches
Classification and retention live in Box. You do not invent a parallel taxonomy nobody will maintain.
A deposit triggers the next step
When a file arrives, the product knows what to do. Fewer blind rereads, more business journey.
Admin approval is in the quote
In enterprise, the app does not talk until an admin authorises it. A developer-account POC does not prove go-live.
Silent outages are monitored
Box can kill a session quietly. We alert and recreate; we do not discover it a month later.
How we deliver your Box connector
Scoping
CCG or JWT, App + Enterprise Access, business folders (not root 0), Events vs webhooks. Admin approval is a milestone, not a detail.
Development
HMAC body+timestamp, one webhook per item with every trigger, 240-upload limiter, persisted Box IDs. A demo every week.
Acceptance
Second webhook refused on the same folder, silent port 8443, "like Stripe" signature, one-hour developer token. Replay before cutover.
Monitoring
Alert on NO_ACTIVE_SESSION, WEBHOOK.DELETED, auto_cleanup. Automated recreation. retry-after honoured.
What the Box API allows
- Files, folders, collaborations
- Stable numeric IDs, root is 0. Comments, tasks, web links, shared links. As-User to act as a managed user.
- Signed v2 webhooks
- POST to address, 30 s timeout, retries up to 12 times over 2 hours. BOX-SIGNATURE-PRIMARY and SECONDARY, version 1, HmacSHA256.
- Enterprise events
- admin_logs: one year, chronological, no duplicates, higher latency. admin_logs_streaming: near real time, two weeks, duplicates possible, order not guaranteed.
- Metadata, retentions, Box Sign
- Business classification and archive duration in Box. Sign in the same API, with its own quota (100 create/resend per min, 1,000 GET).
Box API vocabulary
- CCG
- Client Credentials Grant, default for new server apps. JWT (RSA key, 2FA to generate the pair) remains possible. Switching JWT ↔ CCG can be locked by the enterprise.
- BOX-SIGNATURE-PRIMARY
- HMAC-SHA256 of the body bytes then the timestamp, Base64 digest. Trust if either key (primary or secondary) is valid. 10-minute window. This is not Stripe (hex on the body alone).
- NO_ACTIVE_SESSION
- Trigger delivered when the auth session used at webhook creation has expired. Developer token: one hour. Box considers it delivered; your business no longer sees the real events.
- auto_cleanup
- Webhook deleted if last successful delivery was 30 days ago and more than 14 days between success and last trigger. WEBHOOK.DELETED payload, reason auto_cleanup.
- admin_logs
- Enterprise history up to one year, chronological, no duplicates. The inverse of admin_logs_streaming (2 weeks, duplicates, low latency). We choose, we do not mix the assumptions.
- As-User
- Header to act as a managed user. No wide As-User without a log. App Users: platform model without named credentials.
The real constraints of the Box API
One webhook per item, not the root
FILE.UPLOADED prevents a second FILE.DOWNLOADED webhook on the same folder, same app, same user: update the trigger list. v2 is forbidden on 0. Watching all of Box is the Events API.
240 uploads per minute
Distinct from 1,000 req/min. Search at 6/s is the second cap. 429 with retry-after and code rate_limit_exceeded. Per-enterprise API licence quotas add on top.
The signature is not Stripe's
Body then timestamp, Base64, two keys, 10 minutes. A hex-on-body-only implementation fails 100% of the time. Constant-time compare. Dedupe on the body event id, not BOX-DELIVERY-ID (changes on retry).
Admin approval is not a POC
Enterprise account: the server app waits for an admin. A developer token and a self-authorised free account prove nothing. Port 443 only: :8443 will receive nothing.
Box API or SharePoint API?
Two enterprise DMS. The right one follows the governance already in place, not the SDK.
| Criterion | BoxThis page | Microsoft 365Graph files |
|---|---|---|
| Typical estate | Mid-market and groups outside Microsoft 365 | SharePoint / OneDrive on the tenant |
| Server auth | CCG (2026 default) or JWT, App Users | Entra ID, Sites.Selected |
| Webhook | Payload + HMAC, one per item | Graph signal, delta re-read |
| Audit trail | admin_logs up to one year | sharing delta + application log |
| Signature | Box Sign in the same API | Outside Graph files (Yousign, and so on) |
| Upload | 240 / min / user | Units + 320 KiB session |
| The right case | Box is already the governed DMS | The tenant is already Microsoft 365 |
Google Drive and Dropbox come up on more SME estates. A tender "Box connector" is often a requirement, not an option.
What we measure on a Box integration
The other file APIs
If Box is not the account DMS, these options belong in the scoping conversation.
We combine Box with
The stack around Box on our projects.
Box integration: your questions
Server app on CCG (2026 default) or JWT, App + Enterprise Access if you touch Managed Users, admin approval on an enterprise account, v2 webhooks on business folders (not 0), HMAC before any parsing, Events admin_logs for the estate. Persist IDs, not paths. Limiter 1,000/min and 240 uploads. The hard part is not the first file GET, it is the "one webhook per item" rule and the silent failures Box documents.
A first useful flow, typically a deposit into a client folder plus FILE.UPLOADED into the product, ships in two to three weeks once the app is authorised by an admin. A DMS connector (metadata, Events, Sign, 240/min migration) is closer to six to eight weeks. The admin-approval milestone is not code: it goes into the plan at scoping. This is a scoping call, written down before the first request, not an acceptance surprise.
CCG is the default for new server apps in 2026. JWT (RSA pair, 2FA to generate) remains documented, and switching can be locked by an enterprise setting. A 2022 JWT tutorial is no longer the creation path. We write the choice, secret rotation, and never use a one-hour developer token outside local (it creates NO_ACTIVE_SESSION webhooks). This is a scoping call, written down before the first request, not an acceptance surprise.
Follow the DMS already governed. Box if the company chose not to put files in Microsoft 365, often a tender requirement. SharePoint if the Microsoft tenant is already the disk. Box delivers a signed webhook payload; Graph files deliver a signal to re-read. Drive and Dropbox for more SME estates. This is a scoping call, written down before the first request, not an acceptance surprise. Drive and Dropbox remain the SME discussion, not a substitute for a governed Box estate.
Verify HMAC (body then timestamp, Base64, primary or secondary, 10-minute window, constant-time compare) before any parsing. Raw body. Return 2xx in under 30 s, work in a queue. Dedupe on the body event id, not BOX-DELIVERY-ID. Monitor NO_ACTIVE_SESSION, WEBHOOK.DELETED, auto_cleanup. Port 443, TLS 1.2/1.3, no *.box.com host. This is a scoping call, written down before the first request, not an acceptance surprise.
A Box integration project?
Let's talk. 30 minutes to scope CCG, business folders, webhooks, and tell you plainly what admin approval implies.
Discuss my Box project