Skip to main content

Dropbox

Proxy for the Dropbox API v2 through the managed gateway: file and folder metadata, listing, search, create, move, copy, delete, and upload. All operations are gated by PBAC policy.

Two Dropbox hosts, one connector​

Dropbox splits its API v2 across two hosts: api.dropboxapi.com for RPC-style calls (all of them, including reads, are POST with a JSON body), and content.dropboxapi.com for raw upload/download of file bytes. This connector reaches both. upstream.url_template is the RPC host, and the manifest declares the content host as a named upstream host (upstream.hosts.content); upload_file is the one route that names it ("upstream_host": "content"). Every other tool stays on the RPC host.

Both hosts receive the same upstream credential, so a user links Dropbox once — one OAuth consent or one pasted token — and both read and write tools work. Least privilege is still per tool: reads need dropbox:files:read, writes (including upload) dropbox:files:write. Before PARC-26, upload lived in a separate identos.dropbox-content connector, which needed its own managed resource and its own credential link and offered no OAuth mode.

upload_file's request doesn't fit the gateway's normal JSON body composition: Dropbox expects the raw file bytes as the entire body, with the structured arguments (path, mode, autorename, mute) in a Dropbox-API-Arg header. The route uses the server-side dropbox.upload request-body composer (DropboxUploadComposer.java) to build that shape from the tool's content_base64 and other arguments.

Reading a file's bytes uses the RPC side: get_temporary_download_link calls /files/get_temporary_link, which hands back a 4-hour unauthenticated direct-download URL — fetch that URL with a plain GET to get the bytes, the same pattern identos.ms-onedrive/identos.github use for their own downloads.

There is also no credential probe: every Dropbox v2 endpoint is POST, and the probe mechanism requires a side-effect-free GET/HEAD route, which Dropbox's API doesn't offer. A bad token is caught on the first real call instead of at credential-link time.

Authentication​

Dropbox authenticates REST calls with an access token. This connector supports three auth modes, chosen per managed resource at install time via the Authentication field:

  • OAuth passthrough (idp_passthrough, default, recommended) — each user grants access once through Dropbox's own OAuth consent screen (requires a dropbox IdentityProvider registered on this instance — POST /admin/api/identity-providers, preset in idp-presets/dropbox.json). No token to copy or paste, and it refreshes itself automatically (token_access_type=offline), unlike a hand-generated token that lives until manually rotated.
  • Per-user access token (user_secret) — each user links their own Dropbox access token once, through a PolicyArc-hosted browser page reached by MCP URL elicitation on the first call. The token posts only to the AS (never through the MCP client or the model), is stored encrypted per (subject, resource), and is sent as Authorization: Bearer <token> on that user's calls — so Dropbox attributes every action to the real user, with that user's own account permissions. Use this when a dropbox IdP isn't registered, or a customer prefers pasting a long-lived token over an OAuth consent screen.
  • Shared token (static) — every call uses one operator-held access token from the token_env secret. Dropbox attributes all calls to that one identity.

Either way, PolicyArc enforces per-user authorization at the gateway via policy before the request reaches Dropbox. See Per-user upstream credentials for how the user_secret collection flow works.

Setup​

  • upstream_auth.type — idp_passthrough (default), user_secret, or static.
  • token_env — static mode only — a secret holding a Dropbox access token. Hidden unless static is selected.

Registering the Dropbox IdP (for idp_passthrough)​

Dropbox App Console → create (or reuse) an app with Scoped access. Under OAuth 2, add the AS's /oauth2/callback URL as a Redirect URI, then enable the same five permissions listed below. Register it once via POST /admin/api/identity-providers (or the admin UI's Identity Providers page) with provider_key: "dropbox" — the dropbox.json preset prefills the OAuth endpoints from https://www.dropbox.com's discovery document.

Creating a Dropbox access token​

Dropbox App Console → create (or reuse) an app with Scoped access and App folder access type (sandboxes the app to one dedicated folder — identos.dropbox never needs to see the rest of the account). On the Permissions tab enable account_info.read, files.metadata.read, files.metadata.write, files.content.read, files.content.write — all five, verified live against every route this connector exposes. Dropbox's docs don't cleanly say which of metadata.write/content.write gates which operation (move/copy/delete/create_folder in particular), so this connector doesn't try to split them finely; grant both. Then, on the Settings tab under OAuth 2, click Generate access token. Enabling a scope after a token already exists does not retroactively grant it to that token — generate a fresh one after changing permissions. In user_secret mode each user does this for themselves on the collection page; in static mode the operator provisions the shared token once.

Manifest reference​

  • ID: identos.dropbox
  • Version: 1.1.0
  • Resource type: urn:connector:identos:dropbox
  • Capabilities: mcp

Supported auth modes​

TypeDetails
idp_passthroughrequires IdP dropbox
user_secret—
staticscheme bearer; setup fields: token_env

Setup fields​

IDLabelDefaultSecret?Notes
upstream_auth.typeAuthenticationidp_passthroughnoidp_passthrough (recommended) has each user grant access through Dropbox's own OAuth consent screen — no token to copy or paste, and it refreshes itself. user_secret has each user paste their own long-lived access token instead. static uses one shared token for everyone.
token_envAccess token—yesUsed only for the static method. A secret holding a Dropbox access token, sent as Authorization: Bearer <token>. / shown when upstream_auth.type == 'static'

Scopes​

Scope
dropbox:account:read
dropbox:files:read
dropbox:files:write

Routes​

MethodPatternScopeResource template
POST/users/get_current_accountdropbox:account:read—
POST/files/list_folderdropbox:files:readdropbox://files
POST/files/get_metadatadropbox:files:readdropbox://files
POST/files/get_temporary_linkdropbox:files:readdropbox://files
POST/files/search_v2dropbox:files:readdropbox://files
POST/files/create_folder_v2dropbox:files:writedropbox://files
POST/files/move_v2dropbox:files:writedropbox://files
POST/files/copy_v2dropbox:files:writedropbox://files
POST/files/delete_v2dropbox:files:writedropbox://files
POST/files/uploaddropbox:files:writedropbox://files

MCP tools​

NameScopeDescription
get_current_accountdropbox:account:readGet the Dropbox account info for the token's owner. Useful as a whoami check.
list_folderdropbox:files:readList the contents of a Dropbox folder.
get_metadatadropbox:files:readGet metadata for a file or folder by path.
get_temporary_download_linkdropbox:files:readGet a short-lived (4 hour), unauthenticated direct-download URL for a file. Fetch that URL with a plain HTTP GET (no auth header) to retrieve the bytes — this is how to read file content, since this connector has no raw-bytes download tool. Do not log or persist the URL.
search_filesdropbox:files:readSearch for files and folders by name/content across the account.
create_folderdropbox:files:writeCreate a new folder at the given path.
move_filedropbox:files:writeMove or rename a file or folder.
copy_filedropbox:files:writeCopy a file or folder to a new path.
delete_filedropbox:files:writeDelete a file or folder.
upload_filedropbox:files:writeUpload a file's raw bytes to Dropbox, creating or overwriting it at the given path.