Skip to content

Dropbox

Store file uploads in a Dropbox account via the HTTP API v2. The extension registers a Dropbox-backed implementation of the platform's FileStorageStrategy interface that talks to the Dropbox content and RPC endpoints directly over httpx with OAuth2 refresh-token authentication — no Dropbox SDK dependency. Uploads land under a configurable base folder, and public URLs are served as direct-download shared links.

At a glance
Extension id dropbox
Category storage
Version 0.1.0
Provides FileStorageStrategy implementation (registered as dropbox)
External account Dropbox App — App Key, App Secret, OAuth2 Refresh Token

What It Provides

  • File storage strategy — DropboxStorageStrategy, registered with the strategy resolver as a FileStorageStrategy implementation named dropbox when the extension activates, alongside the built-in local backend.
  • The FileStorageStrategy interface covers four operations: upload bytes under a key (returns a public URL), delete an object, build a browser-accessible public URL for a key, and generate a presigned upload URL — which this backend implements as a Dropbox temporary link (see Operational Notes).
  • The implementation calls the Dropbox HTTP API v2 directly: files/upload, files/delete_v2, sharing/create_shared_link_with_settings, sharing/list_shared_links, and files/get_temporary_link.
  • Nothing else — the package contributes no webhook endpoints, Temporal workflows, schedules, admin pages, GraphQL fields, or event subscriptions.

Setup

  1. Once installed (or dev-linked in development), the extension is discovered at startup. Enable it for a channel from Settings > Extensions (per-channel activation via ChannelExtension).
  2. Per the manifest's install hint: create a Dropbox App at https://www.dropbox.com/developers/apps, then configure the App Key, App Secret, and Refresh Token in the extension's settings (see the wiring warning below).

Configuration Reference

Key Type Required Secret Description
app_key string Yes No App Key
app_secret password Yes Yes App Secret
refresh_token password Yes Yes Refresh Token
access_token password No Yes Access Token (optional, auto-refreshed)
base_folder string No No Base Folder. Defaults to /vectis-uploads.

password-typed fields are encrypted at rest (Fernet) and masked as *** in the admin configuration form.

Credential wiring gap in this version

The activation hook registers DropboxStorageStrategy with empty credentials (app_key="", app_secret="", refresh_token=""), and the extension defines no hot_reload hook — the hook the platform calls to hand freshly saved admin config to a running extension. Values saved through the admin configuration form are stored (secret fields Fernet-encrypted), but no code path in this version passes them to the registered strategy, so its Dropbox API calls cannot authenticate as shipped.

Permissions

The manifest declares no admin permissions (permissions=[]), so no role assignment is needed.

Operational Notes

  • Who calls it — core resolves the active FileStorageStrategy at call time for avatar uploads (POST /api/upload/avatar), media uploads (POST /upload), presigned upload URLs (GET /upload/presign), CMS image derivative generation, and the daily vectis-gc-media-orphans Temporal schedule (GcMediaOrphansWorkflow), which physically deletes purged media objects through the active backend.
  • Which backend wins — every registered backend keeps its name (local, dropbox, s3, ...); when core resolves the storage strategy without naming one, the most recently registered implementation is returned.
  • Token handling — a short-lived access token is fetched from oauth2/token (grant_type=refresh_token, app key/secret as HTTP basic auth) and cached; on a 401 mid-request the cached token is cleared, refreshed once, and the request retried. A configured access_token is used as-is until such a refresh replaces it.
  • File layout — storage keys map to <base_folder>/<key> in the Dropbox account. Uploads use mode: overwrite with autorename: false, so re-uploading a key replaces the file.
  • Public URLs — after an upload the extension reuses an existing direct shared link (sharing/list_shared_links) or creates a public one, then rewrites it to a direct-download URL (www.dropbox.com → dl.dropboxusercontent.com, ?dl=0 → ?dl=1). If link creation fails it falls back to a https://www.dropbox.com/home/... path URL.
  • Temporary links — generate_presigned_url (used by GET /upload/presign) calls files/get_temporary_link; per the code, Dropbox temporary links last 4 hours and the expires parameter is advisory only.
  • Deleting a key that no longer exists in Dropbox (HTTP 409) is logged as a warning and treated as success.
  • All API calls share an httpx client with a 60-second timeout.
  • Avatar uploads fall back to the built-in local backend when the primary backend raises, so a failing Dropbox backend degrades rather than hard-fails that endpoint.
  • See also Storage Extensions in the developer guide.