SwiftyDropbox and the OAuth plumbing behind a Swift file picker

What the SDK actually covers for a Swift app

SwiftyDropbox is the official Dropbox Swift SDK for integrating with the Dropbox API v2 on iOS or macOS. The API itself is HTTP, and a thin HTTP client would work; what the SDK adds is the generated type system for every route, the authentication flow, and the plist and URL scheme configuration that Apple requires for the redirect.

The system requirements are the first filter. The SDK needs iOS 12.0 or later, macOS 10.13 or later, Xcode 13.3 or later and Swift 5.6 or later. Those are the floors stated in the README, and a project on an older toolchain is out regardless of how simple the feature is.

The scope also matters. This is a client for a file storage API on Apple platforms, not a general Dropbox integration for servers or command line tools. A Swift backend service talking to Dropbox would not be the audience the project has in mind.

There is also a versioning split worth knowing before you start. Version 10.0.0 differs greatly from previous versions of the SDK, and the README carries dedicated sections on the changes in version 10.0.0 and on migrating from dropbox-sdk-obj-c, the older Objective-C SDK. Code written against the pre-10 SDK will not simply compile forward.

Registering the app and choosing where the token comes from

Before any API call, your application has to exist in the Dropbox App Console, which creates a record of the app associated with the calls you make. That record is where the app key comes from, and the app key is needed later in the plist configuration.

Every request needs an OAuth 2.0 access token, which represents an authenticated link between a Dropbox app and a Dropbox user account or team. There are two ways to get one.

The quick way is to generate an access token manually in the App Console to authorize your app to access your own Dropbox account. That is a development shortcut, and it is the route that gets you a working first call fastest.

The proper way is to obtain a token programmatically using the SDK's pre-defined auth flow. The README's table of contents has sections for initializing a DropboxClient instance, beginning the authorization flow, and handling the redirect back into the SDK, which is the sequence you follow for a shipping app where a user signs in on device.

The distinction matters because the two paths have different failure modes. A hand-generated token works immediately and tells you nothing about whether the redirect handling in your app is correct, so it can mask a broken configuration until you switch to the programmatic flow.

The plist entries that make the OAuth redirect work

Two plist edits are required, and the README explains the reason for each.

The first registers the Dropbox URL schemes the SDK queries, which lets the Swift SDK determine whether the official Dropbox iOS app is installed on the device. If it is installed, that app can be used to programmatically obtain an OAuth 2.0 access token:

<key>LSApplicationQueriesSchemes</key>
    <array>
        <string>dbapi-8-emm</string>
        <string>dbapi-2</string>
    </array>

The second is the redirect target. Your application has to register to handle a unique Dropbox URL scheme so the system can return to it when the OAuth 2.0 authorization flow completes. The scheme has the format db-<APP_KEY>, where <APP_KEY> is your app's app key from the App Console:

<key>CFBundleURLTypes</key>
    <array>
        <dict>
            <key>CFBundleURLSchemes</key>
            <array>
                <string>db-<APP_KEY></string>
            </array>
            <key>CFBundleURLName</key>
            <string></string>
        </dict>
    </array>

Getting the scheme wrong is the classic failure: the browser completes the authorization, the redirect goes nowhere, and the app appears to hang. The CFBundleURLName entry is left empty in the example, which is what the documentation shows, so copy it as it is rather than inventing a value.

Swift Package Manager and CocoaPods, side by side

Two distribution routes are documented, and they are not equivalent in practice.

Swift Package Manager is the modern path. You add the package by specifying the repository URL in Xcode:

https://github.com/dropbox/SwiftyDropbox.git

The README points at Apple's Adding Package Dependencies to Your App documentation for the rest.

CocoaPods is the older path and needs the tool itself first:

$ gem install cocoapods

Then you create a Podfile, either with pod init or by opening an existing one, and add the pod to the target:

use_frameworks!

target '<YOUR_PROJECT_NAME>' do
    pod 'SwiftyDropbox'
end

Installing and later updating the dependency are separate commands:

$ pod install

$ pod update

One CocoaPods detail is easy to miss. If your project contains Objective-C code that needs access to the Dropbox SDK, there is a separate pod called SwiftyDropboxObjC holding an Objective-C compatibility layer, and it has to be added to the Podfile either in addition to SwiftyDropbox or on its own.

The repository tree shows why the SDK looks the way it does. There is a generate_base_client.py script, a spec directory, a stone directory and a Format directory, which is the client generation and formatting toolchain that produces the route types.

The generated client and its request styles

The README's table of contents lists the request model in three categories, and this is the part of the API that trips up new users.

RPC-style requests are the ordinary JSON calls, the ones that take parameters and return a JSON body. Upload-style requests send file content, and download-style requests return file content. The SDK models each of these differently in Swift, which is why a single flat interface is not possible and why route types are generated rather than hand-written.

Responses come back as a result type per route, with failures expressed as route-specific errors that carry the error payload Dropbox returned for that particular route. The README treats route-specific errors and generic network request errors as separate categories, and it also calls out response handling edge cases as its own subsection, which is a hint that the failure surface is larger than a single error enum.

The client can be customised. There is a section for configuring the network client, which is how you swap or adjust the underlying networking, and a section for specifying the API call response queue, which controls the queue on which responses are delivered.

The class DropboxClientsManager handles the case where you need more than one account. The README splits that into the single Dropbox user case and the multiple Dropbox user case, which is the difference between one client instance and a manager holding several.

Objective-C compatibility and the pre-10 SDK

Two migration paths deserve a paragraph each.

The Objective-C path exists for projects that still contain Objective-C code needing Dropbox access. The compatibility layer ships as its own pod, SwiftyDropboxObjC, and the README links the migration guide from dropbox-sdk-obj-c for teams moving from the old standalone Objective-C SDK rather than from an earlier Swift release.

The 10.0.0 changes are the bigger discontinuity. The README puts a warning at the very top of the document that version 10.0.0 differs greatly from previous versions of the SDK, which tells you the client surface was reshaped rather than extended. If you are maintaining an app that has been on an older major version, budget for that migration rather than a version bump, and read the Changes in version 10.0.0 section before touching the code.

The repository also carries update_version.sh and update_repo_check.sh, scripts that suggest the release process is automated from within the tree. There is a spec directory alongside, which is the API specification the client generator consumes, so a route change on Dropbox's side eventually appears here as a regenerated type.

Maintenance, licence and the App Store privacy question

The repository is not archived and the last push was on 2026-10-20, so work on master is current. The most recent tagged release is 10.2.4 from 2025-12-04, preceded by 10.2.3 in October 2025 and 10.2.2 in September 2025. The gap between the last release and the last commit is normal for a project where release tagging is a separate step, but it does mean the master branch is ahead of what CocoaPods or Swift Package Manager will hand you by default.

The licence is MIT, which means no obligations beyond attribution and preserving the notice, and no copyleft reaching into your application code. No legal advice is offered here beyond naming the identifier.

One section deserves attention before you ship: App Store Connect Privacy Labels. The SDK sits in your app and your app declares its data practices to Apple, so what the SDK transmits matters for that declaration. The README has a dedicated section on it, and it is worth reading rather than guessing, particularly if you request files or tokens.

The tree also includes a .jazzy.json file, which is the configuration for the generated API documentation hosted at the dropbox.github.io address, plus a spec directory and formatting tooling. That documentation is published from the repository, so it moves with the code rather than with a separate site.

Editorial conclusion

SwiftyDropbox is the right choice for an iOS or macOS app that needs Dropbox file access with a Dropbox-managed sign-in flow, because the OAuth redirect handling and the generated route types are the parts of the API v2 that are tedious to get right, and the project is maintained by Dropbox itself. It is the wrong choice for a server-side Swift service, for an app that must use short-lived tokens with its own refresh handling, or for a team that would rather talk to the API over plain HTTP than take on a generated client. Before integrating, confirm your deployment target meets the iOS 12, macOS 10.13, Xcode 13.3 and Swift 5.6 floors, add both the LSApplicationQueriesSchemes entries and the db-<APP_KEY> URL scheme to the plist, and decide on a version pin, since the last tagged release is 10.2.4 from 2025-12-04 while the repository has moved on.

Frequently asked questions

Official sources

1. dropbox/SwiftyDropbox on GitHub
2. Issues
3. License: MIT
4. README
5. Releases