Box to SharePoint migration

A setup reference for moving Box Business / Enterprise content into SharePoint Online document libraries. Covers the two supported credential options (OAuth 2.0 user credential and JWT service-account credential), how Box collaborations translate to SharePoint permissions, what happens to Box Notes, how large media files are handled around Box's API timeouts, and the troubleshooting patterns you'll hit along the way.

How the data flows

MigrationFox streams files directly from Box to SharePoint — no intermediate storage. Folder structure, timestamps, and collaboration metadata are read from the Box API and written to the SharePoint target so the destination library mirrors the source shape within SharePoint's constraints.

Credential options

Box supports two different authentication shapes and both work as a MigrationFox source. Pick based on scope: OAuth for a single user's files, JWT service account for the entire enterprise.

Option A — OAuth 2.0 user credential

Sign in as a Box user or co-admin

What it can see: everything the signing-in user has access to — their own files, shared folders they're a collaborator on, and (for Box co-admins or primary admins) content they've been granted admin visibility over.

In MigrationFox, open Credentials → Add credential → Box.
Choose OAuth. Click Connect with Box.
Sign in as the Box user or admin whose scope you want. Approve the requested scopes.
You're redirected back with the credential stored as an encrypted access + refresh token pair.

Best for: personal / team-scoped migrations, pilots, or enterprises where you want auditable per-user consent.

Option B — JWT service-account credential

App-only access across the Box enterprise

What it can see: every user's content across the Box enterprise, without needing each user to sign in. This is the path for large-scale enterprise migrations.

Go to the Box Developer Console and click Create New App.
Select Custom App, then Server Authentication (with JWT), and name it (e.g. MigrationFox).
On the app's Configuration tab, generate a Public/Private Keypair. Download the resulting JSON config file.
Under App Access Level, choose App + Enterprise Access.
Under Application Scopes, enable Read all files and folders stored in Box and Manage users (for user enumeration).
Submit the app for authorisation by a Box enterprise admin: Admin Console → Integrations → Custom Apps → Authorize, using the Client ID from the app settings.
Back in MigrationFox, choose JWT and upload the config JSON. The credential is validated by minting a test token immediately.

Best for: full enterprise migrations where sign-in-per-user does not scale.

Enterprise-admin approval is required for JWT

Creating the app in the developer console is not enough — until a Box enterprise admin explicitly authorises the app in the Admin Console, every API call will return HTTP 403. This is the most common first-time JWT setup error. If the credential validates but enumerates zero users, the authorisation step is the usual cause.

Collaborations and SharePoint permissions

Box's access model is built on collaborations — per-folder role assignments given to users or groups. SharePoint uses role assignments against libraries and folders. The wizard translates the two models with the following rules:

Box collaboration role	SharePoint role assignment	Notes
Owner	Full Control	Usually collapses to the destination site admin on a cross-tenant move.
Co-owner	Full Control	Same as Owner on the SharePoint side.
Editor	Edit	Write + edit + delete on the item.
Viewer Uploader	Contribute	Can upload but not modify existing items.
Previewer Uploader	Contribute (limited)	SharePoint has no preview-only equivalent; the closest match is Contribute.
Viewer	Read	Read-only.
Previewer	Read	SharePoint does not distinguish preview from read.
Uploader	Contribute (upload-only)	Approximates the Box role.
External collaborator	Guest invite on destination tenant + equivalent SharePoint role	Requires external sharing enabled on the target site.

Group collaborations. Box groups are resolved to their member list and mapped user-by-user against the destination UPN mapping. Group membership changes in Box after the mapping was generated are not picked up mid-run.

Box shared links. Box's public / company-wide shared link URLs do not survive migration — they are Box-specific URLs that disappear the moment files move off the platform. Generate new SharePoint sharing links for anyone still relying on the old Box URLs.

Permission-inheritance shape. Box folders inherit collaborations downward by default; SharePoint does the same with role inheritance. Where a Box folder has different collaborators from its parent (broken inheritance on the Box side), the wizard breaks inheritance on the SharePoint side too and applies the explicit collaborator set.

Box Notes handling

Box Notes are a proprietary, Box-hosted note format — stored as .boxnote files but only editable inside the Box app. They do not move as regular files.

Default behaviour: Box Notes are exported to .docx via the Box API's export endpoint and the resulting Word document is uploaded to the SharePoint destination. Formatting is preserved best-effort — rich text, lists, tables, and inline images carry across; collaborative-cursor state and comment threads do not.
If export fails (e.g. a Note too large to export in one request), the .boxnote file is uploaded as-is and logged in the run report. .boxnote is not readable in SharePoint, so review and manually re-export those Notes after the migration.
Comments on Notes do not migrate. Box's commenting model is not compatible with Microsoft Word's comment anchor format.

Media-endpoint timeouts on large files

The known Box API quirk

Box's download endpoint streams files from a CDN-backed host. For large video and audio files the download stream can stall or disconnect under load before the full content lands — typically around the 30-minute single-request mark, or sooner on flaky upstream links. MigrationFox accounts for this with a chunked download + resumable upload loop so the migration does not fail outright when Box drops the connection.

How the worker handles large media:

Chunked download. Files over a configurable threshold (default 250 MB) are pulled from Box using HTTP range requests. Each chunk is a separate short request, so a single timeout only affects the in-flight chunk, not the whole file.
Chunk-level retry. A failed chunk retries with backoff up to the per-chunk retry budget. If it still fails, the whole file is moved to the retry queue at the end of the run — the other files in the job do not stall.
Chunked upload to SharePoint. The destination side uses SharePoint's resumable upload session, chunk-in-chunk-out, so no full-file buffering happens on the worker.
Total retries, not per-chunk timeouts, bound the cost — a Box media endpoint that repeatedly disconnects is detected and the file is parked in the retry queue rather than burning budget silently.

SharePoint per-file ceiling. SharePoint Online rejects files larger than 250 GB. Box's ceiling is higher for Enterprise Plus plans. Files over the SharePoint ceiling are reported in discovery and skipped during run.

Folder structure and naming

Root mapping. The Box folder you pick as the source root maps to a single SharePoint document library on the destination.
Folder hierarchy is preserved. SharePoint's 400-character path limit is enforced; over-length paths are truncated with a suffix and reported.
Illegal characters are sanitised. SharePoint-forbidden characters (* : < > ? / | ", trailing spaces, leading dots) are replaced with underscores. The original name is preserved in a metadata column on the destination item.
Box Bookmarks (web links) are migrated as .url shortcut files on the SharePoint side. The target URL is preserved; the Box-specific metadata is not.
Versions. Box stores per-file version history. MigrationFox migrates the current version by default; optionally the N most recent versions can be included — each prior version uploads as its own file version on the SharePoint destination.

Running the migration

Add credentials. Box (OAuth or JWT) on the source, Microsoft OAuth on the destination.
Provision destination. Create the target SharePoint site and document library in advance, or let the wizard provision them.
Run a discovery scan. Non-destructive enumeration of the Box source — reports counts, total bytes, largest files, Box Notes present, and any names that will need sanitising.
Configure the job. Pick the source root, the destination library, and optional per-subfolder mappings. Enable collaboration migration to carry access levels across. Decide whether to include prior file versions.
Concurrency. For Box, 5–10 parallel transfers is a reasonable default. Box rate-limits aggressively on per-user API calls, less so on app-only JWT.
Run and monitor. Watch the live dashboard. Failed items (including media-endpoint stalls) are retried; anything still failed at the end lands in the retry queue for one-click re-run.

Troubleshooting

Symptom	Likely cause	Fix
JWT credential validates, but discovery returns 0 users / 0 files	The custom app was created in the developer console but was never authorised by an enterprise admin.	Admin Console → Integrations → Custom Apps → paste the Client ID → Authorize. Rerun discovery.
HTTP 403 on folder enumeration partway through a scan	OAuth user lacks access to a specific sub-tree, or Box admin removed them from a shared folder mid-run.	Switch to JWT service-account auth for full-enterprise scans; otherwise accept that OAuth scans only see the user's own access surface.
Large video files consistently fail with a download timeout	Box media-endpoint stall on a slow upstream link. Happens on multi-gigabyte files.	Expected and handled by chunked download + retry. If a single file fails repeatedly past the retry budget, lower concurrency on the job and re-run just the retry queue.
Box Notes arrive as `.boxnote` files that SharePoint can't open	Export-to-DOCX endpoint failed for those specific Notes.	Review the run report for failed Note exports. Open each in Box and File → Export to Word manually, then upload.
Collaborators show in the Box source but not as SharePoint permissions on the destination	The Box email-to-UPN mapping has unmatched rows, or permission migration was disabled on the job.	Export the mapping report, fix unmatched rows, and run the permissions-only re-run. File content stays; only permissions reapply.
Box shared links no longer work after migration	Box share URLs are Box-specific and do not carry over to SharePoint.	Generate new SharePoint sharing links for the items and communicate the change before cutover.
File names truncated or renamed on the destination	SharePoint's 400-character path limit, or illegal characters in the original name.	Expected. Review the rename report; original names are preserved in a metadata column on each destination item.
Token renewal fails with “invalid_grant” on a long-running JWT job	The app's public key on Box was rotated or revoked while the job was running, or the system clock skew exceeded the JWT assertion window.	Regenerate the keypair in the Box developer console, re-download the config JSON, replace the credential in MigrationFox, and resume.

Dropbox to SharePoint migration — same destination, different source
SharePoint Site Migration — destination-side reference for sites and libraries