---
title: Dropbox integration (file browser and management)
---

# Dropbox integration (file browser and management)

## What it is

Omniscio's Dropbox integration is a **sidebar file browser** for browsing, uploading, downloading, and managing files in your Dropbox account. It connects via Dropbox's REST API v2 using OAuth2 + PKCE (no SDK dependency). The integration follows the channel-adapter pattern: it gets its own virtual project in the sidebar and renders a dedicated file-browsing panel.

## Where to find it

### How to use it

1. **Enable Dropbox.** Settings > **Dropbox** > toggle `dropboxEnabled` on.
2. **Connect your account.** In the Dropbox settings panel, click **Connect Dropbox**. A browser window opens for Dropbox OAuth consent; Omniscio catches the redirect, encrypts the refresh token via `safeStorage`, and stores it.
3. **Browse files.** Click the Dropbox tile in the sidebar. The file browser shows your root folder with breadcrumb navigation, search, and folder creation.
4. **File actions.** Each file row has hover-reveal actions: download, rename, copy shared link, and delete (with confirmation dialog). Folders are clickable to navigate into.

## How it behaves

### How it works

**Auth:** OAuth2 + PKCE flow via `openOAuthPopup()` in [/src/main/services/dropbox/dropbox-auth-service.ts](/src/main/services/dropbox/dropbox-auth-service.ts). Refresh tokens are encrypted at rest via the config store's `CREDENTIAL_FIELDS`. Token refresh supports rotation (Dropbox may issue a new refresh token on each use).

**API:** Direct `globalThis.fetch()` against Dropbox v2 REST endpoints (RPC-style POST JSON to `api.dropboxapi.com/2/` for metadata, `content.dropboxapi.com/2/` for content). All calls route through `dropboxApiCall()` which handles 401 auto-retry with token refresh. Implemented in [/src/main/services/dropbox/dropbox-api-service.ts](/src/main/services/dropbox/dropbox-api-service.ts) with 14 operations: list, list-continue, get, get-content, download, create-folder, upload, delete, move, copy, rename, create-shared-link, search, and get-storage-quota.

**IPC:** 17 typed channels with Zod validation + `wrapHandler()` + output validation in [/src/main/ipc/dropbox-handlers.ts](/src/main/ipc/dropbox-handlers.ts). Error humanization via `friendlyDropboxError()`.

**Renderer:** Zustand store in [/src/renderer/src/features/dropbox/](/src/renderer/src/features/dropbox/) with DropboxProjectView (top-level), DropboxHeader (breadcrumbs + search + actions), DropboxFileList (file listing with pagination), and DropboxFileItem (row with hover-reveal actions using ListItem).

**Settings:** Own section in Settings > Connections > Dropbox with enable toggle and connection management.

**Virtual project:** Sentinel `DROPBOX_PROJECT_ID = '__dropbox__'` in the channel-virtual-projects system. Dashboard routing uses custom `isDropboxSelected` detection before the generic `isChannelProject` check (same pattern as Google Drive).

Settings flag: `dropboxEnabled` in [/src/shared/types.ts](/src/shared/types.ts).

## Related

- [INDEX.md](INDEX.md) — full library index
- [drive-integration.md](drive-integration.md) — Google Drive integration (similar file management, different provider)