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 adropboxIdentityProvider registered on this instance —POST /admin/api/identity-providers, preset inidp-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 asAuthorization: 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 adropboxIdP 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 thetoken_envsecret. 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, orstatic.token_env— static mode only — a secret holding a Dropbox access token. Hidden unlessstaticis 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
| 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 |
POST | /files/upload | 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 this connector has no raw-bytes download tool. 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. |
upload_file | dropbox:files:write | Upload a file's raw bytes to Dropbox, creating or overwriting it at the given path. |
Send feedback about this page