Dropbox App Setup — Chordalia Systems

? What is a Dropbox app — and why do I need one?

Dropbox doesn't let arbitrary desktop applications read your files directly. Instead, apps identify themselves using an App key and App secret — a pair of identifiers created when you register an "app" in the Dropbox developer console.

When a Chordalia product needs Dropbox access, it opens a browser where you sign in to your Dropbox account and approve the request ("This app wants to read your Dropbox files — allow?"). Dropbox remembers your approval and gives the product a refresh token it can use to fetch files from then on.

The App key and App secret don't grant any access on their own. They just tell Dropbox which app is asking when you sign in. The actual permissions are granted (or denied) by you, through the consent screen on Dropbox's site.

Do I have to do this myself? For now, yes — each Chordalia user creates their own Dropbox app. Eventually we'll publish a single Chordalia app you can use without going through this. Until then, the good news is: it's free, takes ten minutes, and everything happens in your own Dropbox account.

What will it cost?

Nothing. Dropbox app registrations are part of the free Dropbox developer programme; they don't require a paid Dropbox plan and they don't consume any storage or bandwidth quotas of their own. The files Chordalia indexes still come out of your normal Dropbox account.

1 Prerequisites

You need a Dropbox account — any plan works, including the free Basic plan. If you've signed in to Dropbox before, you're set.

You do not need a paid developer subscription, a business plan, or admin access. The developer console is just a different page in the same Dropbox account you already have.

Dropbox Business / Team accounts. If your Dropbox is managed by an employer, your admin may have restricted third-party apps. Either use a personal Dropbox account, or ask your admin to whitelist the app you create below in the Dropbox admin console.

2 Open the Dropbox App Console

Go to dropbox.com/developers/apps → and sign in with your Dropbox account.

At the top right of the page, click Create app.

3 Create the app

Fill in the form

Choose an API — pick Scoped access. (The other option, "Dropbox API", is the legacy v1 API and no longer recommended.)
Choose the type of access — pick Full Dropbox.
"App folder" creates a brand-new folder inside your Dropbox and restricts the app to that folder only — useful for apps that create data, not so useful when you want to index files you already have. Pick "Full Dropbox" so the connector can see your existing files.
Name your app — whatever you want, something like Arion Document Search or Chordalia Dropbox. The name must be unique across all Dropbox apps, so you may need to add a number or your name if a generic one is taken. You'll see this name on the consent screen later.

Tick the box agreeing to the API terms, then click Create app. Dropbox creates the app and drops you on its settings page.

4 Add permissions

A new Dropbox app starts with no permissions — it can sign you in but can't read anything. Here you tell Dropbox what categories of data the app is allowed to request.

Steps

At the top of the app's settings page, click the Permissions tab.
Under Files and folders, tick:
- files.metadata.read — lets the app list files and folders.
- files.content.read — lets the app download file contents for indexing.
Leave every *.write and *.delete permission unticked. Chordalia products only need to read your files; they never modify or delete anything in your Dropbox.
Scroll to the bottom and click Submit.

Submit before you copy the keys. If you skip Submit, the permissions don't actually save and the connector will fail with an insufficient_scope error later. Dropbox doesn't make this especially obvious in the UI — always Submit at the bottom of the Permissions tab.

5 Copy the App key and App secret

Go back to the Settings tab. Near the top of the page you'll see two values:

App key — visible in plain text. Click to highlight, then copy. This is one of the two values you need.
App secret — hidden by default. Click Show to reveal it, then copy. This is the second value you need.

The App secret is a secret. Unlike the App key, treat the App secret like a password. Don't commit it to a public repository, paste it in chat logs, or email it. Chordalia products store it locally in your operating system's credential manager (Keychain on macOS, Credential Manager on Windows) so it never sits in a config file once you've completed the OAuth step.

Using your App key and App secret in a Chordalia product

Arion — Dropbox connector

Open Settings → Cloud Sources → enable Dropbox. Paste:

App key → App Key
App secret → App Secret
Folder path → / (whole Dropbox) or a specific folder like /Documents

Click Authorize with Dropbox… — a browser window opens to Dropbox's consent screen. Approve the request, then copy the authorization code Dropbox displays and paste it back into Arion. Arion exchanges the code for a long-lived refresh token, stores it in your OS credential manager, and uses it silently for future syncs.

Then Tools → Sync Cloud Sources to index your Dropbox files for the first time.

! Troubleshooting

"missing_scope" or "insufficient_scope" error during sync

You ticked the permission boxes but didn't click Submit at the bottom of the Permissions tab. Go back to Permissions, confirm files.metadata.read and files.content.read are still ticked, and click Submit. Then in the Chordalia product, click Authorize with Dropbox… again to get a new token with the updated scopes.

"invalid_grant" when exchanging the authorization code

Authorization codes expire quickly (within a few minutes) and are single-use. If you waited too long after copying the code, or accidentally pasted the same code twice, click Authorize with Dropbox… again to start a fresh flow.

"invalid_client: Invalid client_id or client_secret"

Either the App key or App secret was pasted with extra whitespace, or the wrong field was used (App key in the App secret box or vice versa). Re-copy both from the Settings tab in the Dropbox App Console and paste them again.

The consent screen says "This app is in development"

That's normal — Dropbox apps start in development status and only the account that created them can authorize them. As long as you're signing in with the same Dropbox account you used to create the app, you can approve it without the app being formally published.

I can see files but the sync skips them all

Make sure you picked Full Dropbox when creating the app, not App folder. App folder access is restricted to a brand-new folder named after the app, which is empty by default — so the connector finds nothing to index. If you accidentally created an App-folder app, the simplest fix is to delete it and create a new one with Full Dropbox access.

How do I revoke access?

Two options. (1) In the Chordalia product, open Settings, clear the Dropbox section, and save — the stored token is removed. (2) In Dropbox, go to dropbox.com/account/connected_apps → and disconnect the app. Either method invalidates the token immediately; do both if you also want to delete the app entirely.

How do I delete the app entirely?

On the app's Settings page in the Dropbox App Console, scroll to the bottom and click Delete app. The App key and App secret stop working immediately, which also revokes any Chordalia product sessions that were using them.