Dropbox to SharePoint migration

A setup reference for moving Dropbox Business content into SharePoint Online document libraries. Covers the OAuth app registration on the Dropbox side, how Dropbox folder and team-folder structures map into SharePoint libraries, how shared-folder access levels become SharePoint permissions, how large files move through chunked uploads, and how the migration stays authenticated across long-running runs.

How the data flows

MigrationFox streams files directly from Dropbox to SharePoint — no intermediate storage, no local copy. Metadata (timestamps, folder structure, access levels) is read from the Dropbox API and written against the SharePoint target so the destination library matches the source shape as closely as the platforms allow.

OAuth credential setup

Dropbox authenticates through an app you register on your Dropbox developer account. You can either use the MigrationFox-hosted app (the default, easiest path) or register your own and bring your own client ID and secret if your tenant policy requires it.

Default — MigrationFox-hosted OAuth

Click Connect Dropbox, sign in, approve

In MigrationFox, open Credentials → Add credential → Dropbox.
Click Connect with Dropbox. You'll be redirected to Dropbox's consent page.
Sign in as a Dropbox Business admin and approve the requested scopes (see below).
You're redirected back to MigrationFox with the credential stored as an encrypted token pair.

Scopes requested: files.metadata.read, files.content.read, team_data.member, sharing.read, and member-specific file access for team-folder enumeration. All read-only — MigrationFox does not write back to Dropbox.

Advanced — bring your own Dropbox app

Register an app on the Dropbox developer console

Go to dropbox.com/developers/apps and click Create app.
Choose Scoped access, Full Dropbox (or Team folder if you're only migrating team content), and give the app a name.
On the Permissions tab, enable the scopes listed above.
On the Settings tab, add https://app.migrationfox.com/auth/dropbox/callback as a redirect URI.
Copy the App key and App secret into MigrationFox's custom-credential form.

Why register your own: Dropbox Business admins who want the consent to flow through an app they own (for audit log attribution) prefer this path. Functionality is identical to the hosted option.

Folder mapping rules

Dropbox's namespace model does not line up 1:1 with SharePoint. The wizard applies consistent rules so the result is predictable:

Root folder → document library. The Dropbox path you pick as the source root maps to a single SharePoint document library on the destination site.
Team folders → libraries or library subfolders. Each Dropbox team folder can map to its own document library (cleaner permission boundary) or become a subfolder of a shared library. The wizard lets you pick per-team-folder.
Folder hierarchy is preserved. Subfolder nesting is copied verbatim. SharePoint's 400-character path length is enforced — over-length paths are truncated with a suffix and reported at the end of the run.
Illegal characters are sanitised. Characters forbidden in SharePoint names (* : < > ? / | ", trailing spaces, leading dots) are replaced with underscores. The original name is kept in a metadata column so nothing is silently lost.
File requests and camera-upload folders are treated as regular folders; their special Dropbox semantics do not carry across.
Dropbox Paper documents are a proprietary format and are not standard files on the API. Export Paper docs to .docx or .pdf through Dropbox before migrating if you want them in the move.

Shared-folder semantics

Dropbox shared folders carry per-member access levels (editor / viewer, plus owner). SharePoint uses role assignments against the library or folder. The wizard translates the two models with the following rules:

Dropbox access level	SharePoint role assignment	Notes
Owner	Full Control on the destination folder / library	The mapped UPN is granted directly, replacing broken-inheritance-style access.
Editor	Edit	Write + edit + delete.
Viewer	Read	Read-only.
Commenter (Paper only)	Read	Paper-specific — commenting has no SharePoint equivalent.
External (email-only) member	Guest invite on destination tenant + Read/Edit role	Requires the destination tenant to allow external sharing and an invite to go out.

Dropbox shared links (the public or team-link URLs generated for individual files or folders) do not survive migration — they are Dropbox-specific URLs. After migration runs you need to generate new SharePoint sharing links for anyone still relying on an old Dropbox link.

User mapping. Shared-folder members are identified by Dropbox email. The wizard maps each Dropbox email to a Microsoft 365 UPN on the destination tenant. Unmapped emails are reported and skipped on permission assignment (the file content still migrates; only the permission is not applied).

Chunked upload handling for large files

SharePoint rejects single-request uploads larger than 250 MB and times out long-running single-request transfers under load. MigrationFox uses SharePoint's chunked (resumable) upload session endpoint for any file over the small-file threshold:

Under 4 MB — single-request PUT to the SharePoint file endpoint.
4 MB to 250 MB — chunked upload session, default chunk size 10 MB.
250 MB to 15 GB (the SharePoint per-file ceiling) — chunked upload session, larger chunk size, with per-chunk retries on transient failures.
Over 15 GB — rejected and reported. SharePoint does not accept files beyond that size; archive or split before migrating.

Chunk retries. A failed chunk does not fail the whole file — the session is resumable, so the worker retries only the failed chunk. If a transient SharePoint error repeats past the retry budget, the file is failed and moved to the retry queue at the end of the job; you can re-run just the failed items without starting from scratch.

Download side. On the Dropbox side, files over 150 MB use the chunked download endpoint to avoid stalling. Large files therefore stream chunk-in-chunk-out without materialising on disk.

Auth refresh on long migrations

A terabyte-scale Dropbox-to-SharePoint migration can run for days. Both platforms hand out short-lived access tokens that expire mid-run — MigrationFox refreshes silently so the job does not pause.

Dropbox access tokens expire after a few hours. MigrationFox stores the refresh token (alongside the access token, AES-encrypted) and requests a fresh access token when the current one approaches expiry.
Microsoft Graph access tokens expire after roughly an hour. The destination credential holds a refresh token and is renewed the same way.
Refresh-token rotation (Dropbox issues a new refresh token on every refresh) is handled: the new refresh token is written back to the credential record so the next renewal uses it.
Credential revocation mid-run — if an admin revokes the Dropbox or Microsoft credential while a job is running, in-flight transfers fail cleanly with a credential-invalid error and the job surfaces a single “reconnect credential” prompt instead of spamming per-file errors. Reconnect and resume.

Running the migration

Add credentials. Dropbox OAuth and Microsoft OAuth (destination SharePoint tenant). Both are validated before you continue.
Provision destination. Create the target SharePoint site and document library in advance, or let the wizard provision them.
Run a discovery scan. Enumerate the Dropbox source to understand volume, folder depth, and file-type distribution. Discovery is non-destructive and reports counts, total bytes, the largest files, and any names that will need sanitising.
Create the migration job. Pick the source root, the destination library, and optional per-folder mappings. Enable permission migration to pull shared-folder access levels across.
Concurrency. For Dropbox, 5–10 parallel transfers is a good starting point — Dropbox's rate limits are aggressive and a higher number gets throttled to the same effective throughput.
Run and monitor. Watch the live dashboard. Failed items are retried automatically; anything left failed at the end lands in a retry queue you can re-run with one click.

Troubleshooting

Symptom	Likely cause	Fix
Discovery returns 0 items even though Dropbox has data	The Dropbox credential authenticated as a personal account, not a team admin; or the app lacks `team_data.member` scope.	Reconnect with a Dropbox Business admin sign-in. Check that the app was approved with team-level scopes.
Shared-folder members are not getting SharePoint permissions after migration	The 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 put; only permissions reapply.
Large files (over 2 GB) consistently fail	SharePoint upload session timing out, or destination site storage quota is full.	Check the SharePoint site storage quota; increase it if needed. The job auto-retries failed chunks, so genuine file failures after retries point at either quota or a destination-side size limit.
Long-running job pauses with “reconnect credential”	Refresh-token revoked (admin action on Dropbox or Microsoft side), or the refresh flow hit a one-off error that consumed the retry budget.	Click reconnect, re-authorise the credential, resume the job. Already-migrated items are skipped.
Dropbox Paper documents missing from the destination	Paper is a proprietary format that is not a regular file on the Dropbox API.	Export Paper docs to `.docx` or `.pdf` in Dropbox first, then include them in a subsequent run.
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 at the end of the run. Original names are preserved in a metadata column on the destination item.
Dropbox shared links no longer work after migration	Dropbox share URLs are Dropbox-specific and do not carry over to SharePoint.	Generate new SharePoint sharing links for the items. Communicate the change to end users before cutover.

Box to SharePoint migration — same destination, different source platform
SharePoint Site Migration — destination-side reference for site and library setup