Connect Dropbox

Dropbox is a files-only productivity provider. A connected account gives you:

• File and folder metadata through GET /v1/files: names, sizes, content hashes and modified times.
• Change notifications: Dropbox calls your project's webhook URL and the account syncs the change.
• Optional writes: create a folder, rename or move an item, delete an item, and share a file by email.

Dropbox is read-only by default. File contents are never downloaded or uploaded. Dropbox is in Preview. See Preview.

• A Dropbox account that can create apps in the Dropbox App Console.
• A Moira Connect project, selected in the console. Each project registers the Dropbox app it owns.
• A server API key. accounts:read is enough for listing; changing capability selections and writing need accounts:write. See API keys.

1. In the Dropbox App Console, create an app with Scoped access. Choose App folder (the connection sees only that folder) or Full Dropbox access.
2. On the Permissions tab, enable these scopes and submit (you add the redirect URI and webhook URL to this app next):
   • account_info.read identifies the connected account. It is always requested.
   • files.metadata.read lists and reads metadata. Webhooks need it too.
   • files.content.write is what Dropbox requires to create folders and to move, rename and delete items.
   • sharing.write manages sharing. Enable it only if you will share files.

Moira Connect never requests files.content.read or sharing.read. Enable the write scopes before you turn on writes, or Dropbox refuses the consent.

While your Dropbox app is in development, only its owner can link an account. To let other people connect, enable additional users on the app's Settings tab, or apply for production access.

1. Open Provider Apps and choose Dropbox.
2. Copy the Redirect URI, which ends in /oauth/callback/dropbox, and add it under Redirect URIs on the Settings tab of the Dropbox app, exactly as shown.
3. Enter the App key and App secret from the Settings tab and choose Save credentials. The secret is encrypted, never returned, and also verifies Dropbox webhooks. To replace saved credentials, choose Replace credentials, enter both values again and choose Save replacement.
4. Copy the Webhook URL, which ends in /ingress/dropbox/<project id>, and add it under Webhooks on the Settings tab, exactly as shown. Do this after step 3: Dropbox checks the URL when you add it, and Moira Connect answers only for a project that already has a Dropbox app.

The webhook URL uses a different host from the API and the redirect URI, so copy both from the console. It needs a selected project.

1. Open Connect account and choose Dropbox.
2. Enter an Account reference, your own label for the connection. Give each account its own reference: a reference that is already in use points at the account that has it instead of creating another one.
3. Select Connect Dropbox. The console opens the Dropbox consent in a new tab and shows Connection started.
4. Approve the Dropbox consent screen. The account becomes ready.

The consent lists account_info.read and files.metadata.read, the read-only baseline. The console has no service picker for Dropbox, so write scopes appear only after you set capability selections (see Enable writes). An account stays tied to the Dropbox account that first authorized it.

The first sync lists everything in the Dropbox. A large Dropbox takes several minutes, and GET /v1/files returns a partial list meanwhile. After that, a webhook notification triggers a sync, and each active account also syncs about every 15 minutes. A sync that fails on a network, server or throttling error waits 30 seconds, doubling up to 15 minutes, or as long as Dropbox's Retry-After asks, up to 1 hour. A throttle without a Retry-After waits 60 seconds. GET /v1/accounts/{id}/sync-status shows the latest run.

The response has data.items and data.next_cursor, newest provider_modified_at first, and limit is clamped to 1 to 100. GET /v1/files/{id} returns one file by its UUID id. For Dropbox:

• drive_ref is always default, and provider_file_id is the Dropbox id.
• A folder has mime_type application/vnd.dropbox.folder and no modified time, so it sorts after the dated files. A file has no mime_type.
• parent_refs is empty and web_url is null.

Changes arrive as drive.file.upserted and drive.file.deleted events. An item deleted in Dropbox stays in the list with trashed: true, and deleting a folder trashes the items beneath it.

A console-connected account is read-only unless the project has capability selections for Dropbox. The write capabilities are:

• drive.file.create, drive.file.update and drive.file.delete create folders, rename or move items, and delete items. They need files.content.write.
• drive.permission.manage shares files and needs sharing.write.

Enable those scopes on the Dropbox app first. PUT /v1/capability-selections replaces every selection of its scope, so list every capability you want.

A new connection requests only the capabilities you enable, so include drive.file.read or the consent screen drops files.metadata.read. Reconsent and the write checks fall back to the default for a capability without a row, and for Dropbox only drive.file.read is on by default. Pass account_id to select for one account instead of the whole project.

To apply the selections to a connected account, call POST /v1/accounts/{id}/reconsent (with an Idempotency-Key header) and open the returned url. The body must hold at least one of success_redirect_url, webhook_id or opener_origin, or the request fails with a 422 and the code completion_target_required.

Connecting again from the console with a reference that is already in use starts no new consent for an account that is ready, and a different reference makes a second account. Reconnect / adjust services is shown for Google and Microsoft accounts only, so use the API for a Dropbox account.

Every write is an asynchronous command. It needs an Idempotency-Key header, returns 202 with command_id, status and created_at, and its result is read with GET /v1/commands/{command_id}.

• Create a folder with POST /v1/files, sending account_id and name. parents takes at most one folder id, or root for the top level. Dropbox cannot create files this way.
• Rename or move with PATCH /v1/files/{id}; only name and parents can change. Delete with DELETE /v1/files/{id}.
• Share a file with POST /v1/files/{id}/permissions and {"type":"user","role":"reader","email":"[email protected]"}. role is reader or writer.

A name must be 1 to 255 characters without /, \ or control characters. If the capability is not selected and consented for the account, the command is accepted and then fails with capability_not_granted. GET /v1/files/{id}/permissions returns only the members you shared with through the API.

Dropbox has preview availability in GET /v1/public/providers, and the public catalog offers no Connect link for it.

Separately, POST /v1/hosted-connect-sessions cannot create a new Dropbox connection, because it accepts only a fixed list of providers and Dropbox is not on it. That is not a consequence of Preview. Create the connection from the console. A request with account_id reconnects an existing account.

• Metadata only: no file content is downloaded or uploaded, and there is no export.
• Writes create folders only. Files cannot be created, edited or uploaded, and folders cannot be shared.

• Dropbox rejects the webhook URL. Save the app key and secret in Moira Connect first: a project with no Dropbox app returns 404.
• Dropbox refuses the consent screen or the redirect. The redirect URI must be exactly the one the console shows, and every scope requested must be enabled on the Permissions tab and submitted.
• Someone other than you cannot connect. See Create the Dropbox app.
• Changes do not appear. Check that the webhook URL is registered and enabled in the Dropbox App Console and that files.metadata.read is enabled. A webhook that returns 401 means the app secret in Moira Connect is not the Dropbox app's. Without a notification, the account still syncs about every 15 minutes.
• The account needs reauthorization. Dropbox reported the token invalid or the refresh grant no longer valid. Reconsent with POST /v1/accounts/{id}/reconsent. An expired access token is refreshed automatically.
• A command fails with capability_not_granted. Set the selections and reconsent.
• A command fails with path_conflict, parent_not_found, parent_not_folder, invalid_name or unsupported_target. A folder exists at that path, the parent is unknown or not a folder, the name is invalid, or you tried to share a folder. A share that fails with member_error was not accepted by Dropbox.

A request body must be a JSON object sent with Content-Type: application/json, otherwise the request fails with invalid_json or unsupported_media_type. See Errors for the other status codes.

Connect one account with the read baseline, wait for the first listing, and compare GET /v1/files with Dropbox before you turn on writes.