How to Integrate Bolt.new with Dropbox

Register a Dropbox application at dropbox.com/developers/apps. Click 'Create app', then make these choices: API — Dropbox API (not Scoped App, which is for Dropbox Business). App folder access vs Full Dropbox — choose 'App folder' for apps that only need one dedicated folder (simpler permission, Dropbox creates /Apps/YourAppName in the user's Dropbox), or 'Full Dropbox' for apps that need to browse the user's entire Dropbox. Give the app a unique name. On the app settings page, you will find the App key (this is your OAuth client ID — Dropbox calls it 'App key', not 'Client ID'). Under OAuth 2.0, set the Redirect URI to your deployed callback URL: https://your-app.netlify.app/api/auth/dropbox/callback. Note: add localhost:3000 as a second redirect URI for local development testing. For permissions, go to the Permissions tab and enable: files.content.read (download files), files.content.write (upload and modify files), files.metadata.read (list folders), sharing.write (create shared links). Save changes. Dropbox permissions must be set before generating tokens — changing permissions requires users to re-authorize. Dropbox now uses short-lived access tokens (4 hours) with refresh tokens by default. The older long-lived tokens are being deprecated. During development, you can generate a test access token on the app settings page under OAuth 2 → Generated access token — this gives you a long-lived token for rapid development iteration without implementing the full OAuth flow first.

1# .env
2DROPBOX_APP_KEY=your_dropbox_app_key
3DROPBOX_APP_SECRET=your_dropbox_app_secret
4DROPBOX_REDIRECT_URI=https://your-app.netlify.app/api/auth/dropbox/callback
5
6# For development testing only (generated on Dropbox app settings page):
7# DROPBOX_TEST_TOKEN=sl.xxxxxxxxxxxxxxxxxxxxxxxxxxxx
8# Remove before production deployment!

Install the official Dropbox JavaScript SDK using the package name 'dropbox'. This SDK wraps Dropbox API v2's RPC-style endpoints into typed methods, handling the request format (JSON body POSTs), authentication headers, and response parsing. The package is pure JavaScript with no native binaries — it installs and works in Bolt's WebContainer. The Dropbox SDK is initialized with your App key for OAuth flows, or with an access token for API calls. Create two utility files: one for OAuth URL generation and token exchange (uses App key + App secret), and one that creates an authenticated Dropbox client instance from a stored access token. Dropbox API v2's RPC format note for Bolt prompting: when prompting Bolt to call Dropbox methods, reference the SDK method names (filesListFolder, filesUpload, sharingCreateSharedLinkWithSettings) rather than the raw API endpoints. Bolt generates cleaner SDK-based code when you reference method names. The SDK method names match the Dropbox API documentation endpoints with camelCase: /files/list_folder → filesListFolder, /files/upload → filesUpload, /sharing/create_shared_link_with_settings → sharingCreateSharedLinkWithSettings.

1// lib/dropbox-client.ts
2import { Dropbox } from 'dropbox';
3
4export function getDropboxClient(accessToken: string): Dropbox {
5  return new Dropbox({ accessToken });
6}
7
8// lib/dropbox-auth.ts
9function base64urlEncode(buffer: ArrayBuffer): string {
10  return Buffer.from(buffer)
11    .toString('base64')
12    .replace(/\+/g, '-')
13    .replace(/\//g, '_')
14    .replace(/=/g, '');
15}
16
17export async function generateCodeChallenge(verifier: string): Promise<string> {
18  const encoded = new TextEncoder().encode(verifier);
19  const hash = await crypto.subtle.digest('SHA-256', encoded);
20  return base64urlEncode(hash);
21}
22
23export function generateCodeVerifier(): string {
24  const array = new Uint8Array(32);
25  crypto.getRandomValues(array);
26  return base64urlEncode(array.buffer);
27}
28
29export async function buildAuthUrl(codeVerifier: string): Promise<string> {
30  const challenge = await generateCodeChallenge(codeVerifier);
31  const params = new URLSearchParams({
32    client_id: process.env.DROPBOX_APP_KEY!,
33    response_type: 'code',
34    redirect_uri: process.env.DROPBOX_REDIRECT_URI!,
35    code_challenge: challenge,
36    code_challenge_method: 'S256',
37    token_access_type: 'offline', // Enables refresh tokens
38  });
39  return `https://www.dropbox.com/oauth2/authorize?${params}`;
40}

Dropbox recommends PKCE (Proof Key for Code Exchange) for OAuth 2.0. PKCE enhances security for public clients by generating a cryptographic verifier before the authorization request and proving possession of that verifier during token exchange — preventing authorization code interception attacks. The PKCE flow requires two API routes. The initiation route generates a code_verifier (a random 32-byte string, base64url encoded), hashes it with SHA-256 to create the code_challenge, stores the verifier in an httpOnly cookie (needed for the callback), and redirects the user to Dropbox's authorization page with the code_challenge. The callback route receives the authorization code from Dropbox, reads the code_verifier from the cookie, exchanges both for access and refresh tokens, and stores the tokens securely. This OAuth flow only completes on a deployed app where the redirect URI matches exactly. During development in Bolt, you have two options: (1) deploy to Netlify first and test OAuth there, or (2) use a development access token from the Dropbox app settings page (App Settings → Generated access token) to test file operations independently without implementing OAuth. The generated development token works for testing filesListFolder, filesUpload, etc., without going through the OAuth flow — useful for building and testing the file operation UI before the OAuth plumbing is complete.

1// app/api/auth/dropbox/route.ts
2import { NextResponse } from 'next/server';
3import { buildAuthUrl, generateCodeVerifier } from '@/lib/dropbox-auth';
4
5export async function GET() {
6  const codeVerifier = generateCodeVerifier();
7  const authUrl = await buildAuthUrl(codeVerifier);
8  const response = NextResponse.redirect(authUrl);
9  response.cookies.set('dropbox_cv', codeVerifier, {
10    httpOnly: true,
11    secure: true,
12    maxAge: 600,
13    sameSite: 'lax',
14  });
15  return response;
16}
17
18// app/api/auth/dropbox/callback/route.ts
19import { NextRequest, NextResponse } from 'next/server';
20
21export async function GET(request: NextRequest) {
22  const { searchParams } = new URL(request.url);
23  const code = searchParams.get('code');
24  const codeVerifier = request.cookies.get('dropbox_cv')?.value;
25
26  if (!code || !codeVerifier) {
27    return NextResponse.redirect('/login?error=missing_params');
28  }
29
30  const tokenRes = await fetch('https://api.dropboxapi.com/oauth2/token', {
31    method: 'POST',
32    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
33    body: new URLSearchParams({
34      code,
35      grant_type: 'authorization_code',
36      client_id: process.env.DROPBOX_APP_KEY!,
37      client_secret: process.env.DROPBOX_APP_SECRET!,
38      redirect_uri: process.env.DROPBOX_REDIRECT_URI!,
39      code_verifier: codeVerifier,
40    }),
41  });
42
43  const tokens = await tokenRes.json();
44  if (tokens.error) {
45    return NextResponse.redirect(`/login?error=${tokens.error}`);
46  }
47
48  const response = NextResponse.redirect('/dashboard');
49  response.cookies.set('dropbox_at', tokens.access_token, { httpOnly: true, secure: true, maxAge: 14400 });
50  if (tokens.refresh_token) {
51    response.cookies.set('dropbox_rt', tokens.refresh_token, { httpOnly: true, secure: true, maxAge: 86400 * 30 });
52  }
53  response.cookies.delete('dropbox_cv');
54  return response;
55}

With authentication in place, implement the file operations your app needs using the Dropbox SDK. The SDK's method signatures follow Dropbox API v2's RPC naming — remember that listing and reading files uses POST requests under the hood, but the SDK presents them as straightforward method calls. Key SDK methods for common operations: - List folder: dropbox.filesListFolder({ path: '' }) for root (empty string, not '/'), returns result.entries array of FileMetadata and FolderMetadata objects - List with pagination: check result.has_more, then call dropbox.filesListFolderContinue({ cursor: result.cursor }) until has_more is false - Download file: dropbox.filesDownload({ path: '/path/to/file.pdf' }) — in Node.js, the response contains a fileBlob property with the binary content - Upload file: dropbox.filesUpload({ path: '/target/path/file.pdf', contents: Buffer.from(fileContent), mode: { '.tag': 'add' }, autorename: true }) - Create folder: dropbox.filesCreateFolderV2({ path: '/NewFolder', autorename: false }) - Create sharing link: dropbox.sharingCreateSharedLinkWithSettings({ path: '/file.pdf', settings: { requested_visibility: { '.tag': 'public' } } }) Error handling: Dropbox SDK methods throw errors with an error.error property containing the Dropbox error object, which has a '.tag' field identifying the error type. Common tags: 'path' for path errors, 'too_many_requests' for rate limiting, 'expired_access_token' for auth errors.

1// app/api/dropbox/files/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { getDropboxClient } from '@/lib/dropbox-client';
4
5export async function GET(request: NextRequest) {
6  const accessToken = request.cookies.get('dropbox_at')?.value;
7  if (!accessToken) return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });
8
9  const { searchParams } = new URL(request.url);
10  const path = searchParams.get('path') || '';
11
12  const dbx = getDropboxClient(accessToken);
13
14  try {
15    const result = await dbx.filesListFolder({ path });
16    const files = result.result.entries.map((entry) => ({
17      name: entry.name,
18      path_lower: entry.path_lower,
19      isFolder: entry['.tag'] === 'folder',
20      size: entry['.tag'] === 'file' ? entry.size : undefined,
21      modified: entry['.tag'] === 'file' ? entry.server_modified : undefined,
22    }));
23    return NextResponse.json({ files, cursor: result.result.cursor, hasMore: result.result.has_more });
24  } catch (error: unknown) {
25    const e = error as { status?: number; error?: { error_summary?: string } };
26    if (e.status === 401) return NextResponse.json({ error: 'Token expired' }, { status: 401 });
27    return NextResponse.json({ error: e.error?.error_summary || 'Dropbox error' }, { status: 500 });
28  }
29}