Setup
Box takes a developer token (quickest), an OAuth refresh token (long-running), a PKCE refresh token (browsers) or client credentials (a service account).Quick Start: Developer Token (60 minutes, no OAuth)
- In the Developer Console, click New App, pick the User type (OAuth 2.0) and click Create.
- On the Configuration tab, under Developer Token, click Generate Developer Token and copy it.
OAuth refresh token (long-running)
OAuth refresh token (long-running)
-
Create a User app as above. On its Configuration tab:
- Under OAuth 2.0 Redirect URIs, add
http://localhost:1(and any browser or production callback). - Under Application Scopes, check Read all files and folders stored in Box, plus Write all files and folders stored in Box for a write mount.
- Copy the Client ID and Client Secret, then Save Changes.
- Under OAuth 2.0 Redirect URIs, add
- In an enterprise, a Box admin may have to enable the app before it issues tokens. Personal accounts skip this.
-
Open this URL with
YOUR_CLIENT_IDreplaced, sign in and click Grant access: -
The browser goes to
http://localhost:1/?code=..., a page that does not load. The code is valid for 30 seconds, so exchange it at once:
refresh_token. Set client_id, client_secret and
refresh_token (BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_REFRESH_TOKEN).Service account (client credentials)
Service account (client credentials)
- In the Developer Console, click New App, pick the Server type and keep Client Credentials Grant.
- A Box admin authorizes it in the Admin Console under Platform > Platform Apps, adding it by Client ID. Free developer accounts are authorized on creation.
- Set
client_id,client_secretandenterprise_id(BOX_CLIENT_ID,BOX_CLIENT_SECRET,BOX_ENTERPRISE_ID).
Browser sign-in with PKCE (no client secret)
Browser sign-in with PKCE (no client secret)
The TypeScript
BoxVFS from @struktoai/mirage-browser takes clientId
and refreshToken with no secret.- Add
http://localhost:5173/vfs/box/box_pkce.htmlto OAuth 2.0 Redirect URIs andhttp://localhost:5173to the CORS origins below. - Set only
BOX_CLIENT_IDin.env.development. - Run
pnpm devinexamples/browser/and open that URL. - Click Connect Box.
localStorage through
onRefreshTokenRotated, so a reload needs no new sign-in.Token lifetime and troubleshooting
Token lifetime and troubleshooting
on_refresh_token_rotated (TypeScript onRefreshTokenRotated)
to persist it across restarts.
CORS notes
A browser can call Box only from origins listed under CORS Domains (some consoles say Allowed Origins) on the app’s Configuration tab. Each origin must match exactly: no trailing slash, and the protocol counts.Connect
- YAML
- Python
- TypeScript
workspace.yaml
Layout
- Every item keeps its name and raw bytes.
.boxnoteand.boxcanvasare JSON;.gdoc,.gsheetand.gslidesare the Office zips Box stores (mount Google Drive for an editable view). - Box addresses items by numeric ID; the mount resolves each path one folder level at a time and caches the result.
root_folder_id(frombox.com/folder/<id>) mounts one folder and survives renames and moves.
Sample runs
write mount, tee, cp, mv, rm and mkdir change Box; the app
needs the Write all files and folders stored in Box scope.
SDK guides
Python
Every config field, the VFS.md and write support.
TypeScript
Every config field, the VFS.md and write support.