Skip to main content
A Box account, or one folder of it, becomes a folder tree of its real files, served as raw bytes.

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)

  1. In the Developer Console, click New App, pick the User type (OAuth 2.0) and click Create.
  2. On the Configuration tab, under Developer Token, click Generate Developer Token and copy it.
The token lasts 60 minutes and cannot be renewed by code: generate a new one by hand, or use a refresh token below for long runs.
  1. 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.
  2. In an enterprise, a Box admin may have to enable the app before it issues tokens. Personal accounts skip this.
  3. Open this URL with YOUR_CLIENT_ID replaced, sign in and click Grant access:
  4. 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:
The reply holds refresh_token. Set client_id, client_secret and refresh_token (BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_REFRESH_TOKEN).
  1. In the Developer Console, click New App, pick the Server type and keep Client Credentials Grant.
  2. 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.
  3. Set client_id, client_secret and enterprise_id (BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_ENTERPRISE_ID).
Tokens are minted for the app’s service account and fetched again on expiry, with no refresh token. The service account starts with an empty root: share folders with its email address to see them.
The TypeScript BoxVFS from @struktoai/mirage-browser takes clientId and refreshToken with no secret.
  1. Add http://localhost:5173/vfs/box/box_pkce.html to OAuth 2.0 Redirect URIs and http://localhost:5173 to the CORS origins below.
  2. Set only BOX_CLIENT_ID in .env.development.
  3. Run pnpm dev in examples/browser/ and open that URL.
  4. Click Connect Box.
The example saves each rotated refresh token to localStorage through onRefreshTokenRotated, so a reload needs no new sign-in.
Box rotates the refresh token on every refresh. Mirage keeps the newest one in memory; pass 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

workspace.yaml

Layout

  • Every item keeps its name and raw bytes. .boxnote and .boxcanvas are JSON; .gdoc, .gsheet and .gslides are 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 (from box.com/folder/<id>) mounts one folder and survives renames and moves.

Sample runs

On a 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.