Dropbox JavaScript SDK

Client-side applications (browsers or Workers) cannot keep an app secret confidential. Never embed a Dropbox app secret in browser or Worker code.

Instead, use the OAuth authorization-code flow with PKCE (Proof Key for Code Exchange) and your app key. PKCE requires a secure context and the Web Crypto API.

The SDK supports Node.js 22+, modern web browsers, and Web Workers.

Required APIs:

• Promise
• fetch
• TextEncoder
• Web Crypto API (required specifically for PKCE authentication)

If you are targeting older environments that do not provide these APIs, you must add polyfills.

The SDK now includes node-fetch as a dependency for Node.js environments and falls back to window.fetch in browsers.

Recommendation: Do not pass your own fetch implementation to the Dropbox constructor unless necessary (e.g., for mocking). If you must pass a custom fetch, ensure you bind it to the appropriate context:

// Example if passing custom fetch
new Dropbox({ fetch: your_fetch.bind(your_context) });

The Code Flow example demonstrates a backend-based authentication flow. To set it up:

1. Clone the repository.
2. Run npm install and npm run build in the root of the repository.
3. Create an app in the Dropbox App Console.
4. In the App Console, set the redirect URI to http://localhost:3000/auth.
5. Configure your credentials in examples/javascript/simple-backend/code_flow_example.js by setting the app key and secret on lines 17 and 18.
6. Run the example: node examples/javascript/simple-backend/code_flow_example.js.
7. Open your browser and navigate to http://localhost:3000/.

API responses are now wrapped in a DropboxResponse object. To access the actual data (like fileBlob or fileBinary), you must now access the .result property. This object also provides access to .status and .headers.

Old: console.log(response.fileBlob);

New: console.log(response.result.fileBlob); console.log(response.status); console.log(response.headers);

var response = dbx.usersGetCurrentAccount();
console.log(response.result.fileBlob); // or fileBinary if using workers
console.log(response.status);
console.log(response.headers);

To run the TypeScript-based examples (such as basic, download, team, team-as-user, or upload), follow these steps:

1. Clone the repository.
2. Install dependencies and build the project: npm install and npm run build.
3. Execute the specific example file using Node.js. For example, to run the basic example: node basic.

In v9.0.0, generatePKCECodes and getAuthenticationUrl were changed from synchronous to asynchronous to ensure consistent behavior between Node and the Browser. You must now treat these methods as returning Promises.

Old Synchronous Pattern:

var authUrl = dbxAuth.getAuthenticationUrl(redirectUri, null, 'code', 'offline', null, 'none', false)
// logic for navigating to authUrl

New Asynchronous Pattern:

dbxAuth.getAuthenticationUrl(redirectUri, null, 'code', 'offline', null, 'none', false)
    .then((authUrl) => {
        // logic for navigating to authUrl
    });

The authenticateWithCordova function is deprecated because it relies on in-app browsers (web-views), which is discouraged for security.

To support authentication in native apps, implement the following flow:

1. Call getAuthenticationUrl with your app's parameters (using PKCE is highly recommended for security).
2. Open the resulting authentication URL in the device's default system browser.
3. Use a custom URI scheme to redirect the user back into your app once the OAuth flow is complete.

TypeScript definitions have moved from the DropboxTypes namespace to the Dropbox namespace.

Old: const result: DropboxTypes.users.FullAccount = ...

New: const result: Dropbox.users.FullAccount = ...

To run the web-based JavaScript examples in your local development environment, follow these steps:

1. Clone the repository.
2. Install dependencies and build the project: npm install and npm run build.
3. Start the development server: node server.js.
4. Open your browser and navigate to http://localhost:8080/.

A TypeScript bug was fixed where routes with no arguments required a void argument (e.g., passing null). You can now call these methods without any arguments.

// Old way (required null for TypeScript compatibility)
var result = dbx.usersGetCurrentAccount(null);

// New way
var result = dbx.usersGetCurrentAccount();