Setup
Create a Dropbox app, give it file permissions and trade one sign-in for a long-lived refresh token. Mirage mints the short-lived access tokens (about 4 hours) from it and renews each one 5 minutes before it expires.1. Create a Dropbox app
1. Create a Dropbox app
- Open the App Console and click Create app.
- Choose Scoped access.
- Choose App folder (one folder Dropbox creates for the app, the least privilege) or Full Dropbox (the whole account).
- Name it (for example “Mirage”) and click Create app.
2. Set permissions
2. Set permissions
On the Permissions tab, check:
Click Submit. Dropbox leaves unchecked scopes out of tokens, even
when the sign-in URL asks for them.
3. Get the refresh token
3. Get the refresh token
-
On the Settings tab, add
http://localhost:1under OAuth 2 > Redirect URIs, then copy the App key and the App secret. -
Open this URL in a browser, with
YOUR_APP_KEYreplaced.token_access_type=offlineis required for a refresh token: -
Sign in and click Allow. The browser goes to
http://localhost:1/?code=..., a page that does not load. Copy thecodevalue and exchange it right away:
refresh_token (and expires_in: 14400 for the
access token). Save the refresh token.Browser sign-in with PKCE (no app secret)
Browser sign-in with PKCE (no app secret)
A browser app can skip the app secret: the TypeScript
DropboxVFS from
@struktoai/mirage-browser takes only clientId and refreshToken.- Add
http://localhost:5173/vfs/dropbox/dropbox_pkce.htmlto the Redirect URIs. It must match exactly, with no trailing slash. - Set only
DROPBOX_APP_KEYin.env.developmentat the repo root. - Run
pnpm devinexamples/browser/and open that URL. - Click Connect Dropbox.
localStorage. The same token
works headless as DROPBOX_REFRESH_TOKEN.Troubleshooting
Troubleshooting
A refresh token lasts until it is revoked: the user disconnects the app
at connected apps, or
the app is deleted.
Connect
- YAML
- Python
- TypeScript
workspace.yaml
Layout
root_path(such as/Team/data) mounts one folder; an App folder app sees only its own folder.- Files keep their names and bytes.
grep -rwasks Dropbox search first; below the Professional plan it matches file names only.
Sample runs
write mount, tee, cp, mv, rm and mkdir change Dropbox and
need files.content.write. rmdir fails with ENOTEMPTY on a non-empty
folder; rm -r removes it.
SDK guides
Python
Every config field, the VFS.md and write support.
TypeScript
Every config field, the VFS.md and write support.