Dropbox

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

identos.dropbox and identos.dropbox-content both name a scope dropbox:files:write. The gateway does not refuse a token of another connector type whose scope names match a route's scope (see Check the scope and resource). In our run a client_credentials token issued for the identos.dropbox type with dropbox:files:write got 200 from an identos.dropbox-content resource's upload_file, over REST and over MCP. We did not run the reverse direction. dropbox:files:write and calendar:read (Google and Microsoft calendar) are the only scope names that two shipped connectors share.

Scope: RPC host — read file content via a link, not inline bytes

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 targets only the RPC host — a managed resource has one fixed upstream base URL, so it can't also reach the content host.

That still covers reading a file's actual content: get_temporary_download_link calls the RPC-side /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. Writing raw bytes has no RPC-side equivalent, so upload lives in the companion identos.dropbox-content connector, pointed at the content host. Install both for full read/write file access; everything else (list, get_metadata, search, create_folder, move, copy, delete) is metadata and lives here.

There is also no credential probe. Every Dropbox v2 endpoint is POST, and the connector manifest schema allows a probe only on a GET or HEAD route. 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 idpId: "dropbox", issuer: "https://www.dropbox.com" and the app's client ID and secret. The dropbox.json preset matches on that idpId and fills in the OAuth endpoints.

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.0.0
• Resource type: urn:connector:identos:dropbox
• Capabilities: mcp

Supported auth modes

Type	Details
idp_passthrough	requires IdP dropbox
user_secret	—
static	scheme bearer; setup fields: token_env

Setup fields

ID	Label	Default	Secret?	Notes
upstream_auth.type	Authentication	idp_passthrough	no	idp_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_env	Access token	—	yes	Used 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

Method	Pattern	Scope	Resource template
POST	/users/get_current_account	dropbox:account:read	—
POST	/files/list_folder	dropbox:files:read	dropbox://files
POST	/files/get_metadata	dropbox:files:read	dropbox://files
POST	/files/get_temporary_link	dropbox:files:read	dropbox://files
POST	/files/search_v2	dropbox:files:read	dropbox://files
POST	/files/create_folder_v2	dropbox:files:write	dropbox://files
POST	/files/move_v2	dropbox:files:write	dropbox://files
POST	/files/copy_v2	dropbox:files:write	dropbox://files
POST	/files/delete_v2	dropbox:files:write	dropbox://files

MCP tools

Name	Scope	Description
get_current_account	dropbox:account:read	Get the Dropbox account info for the token's owner. Useful as a whoami check.
list_folder	dropbox:files:read	List the contents of a Dropbox folder.
get_metadata	dropbox:files:read	Get metadata for a file or folder by path.
get_temporary_download_link	dropbox:files:read	Get 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 Dropbox's raw-bytes download API lives on a separate host this connector doesn't reach. Do not log or persist the URL.
search_files	dropbox:files:read	Search for files and folders by name/content across the account.
create_folder	dropbox:files:write	Create a new folder at the given path.
move_file	dropbox:files:write	Move or rename a file or folder.
copy_file	dropbox:files:write	Copy a file or folder to a new path.
delete_file	dropbox:files:write	Delete a file or folder.