Box

​

Overview

• /folders/{id}/items, list folder items (root id is 0)
• /files/{id}/content, download file bytes
• /files/{id} / /folders/{id}, fetch entry metadata
• /search, search files by name/content
• /oauth2/token, refresh access tokens

• Developer token, fastest first-run path. Click one button in the Box app console, paste the 32-char access token, and you’re done. Lives 60 minutes; you regenerate by hand. No client_id / refresh_token / OAuth flow needed. Recommended for mirage exploration.
• Code flow with client secret, for Node/server long-running use. Needs client_id, client_secret, refresh_token.
• PKCE flow, for browsers. Needs only client_id and refresh_token (no secret in the bundle).

​

Quick Start: Developer Token (60 minutes, no OAuth)

1. Go to https://app.box.com/developers/console -> Create New App -> Custom App -> User Authentication (OAuth 2.0) -> name it “Mirage” -> Create App
2. On the Configuration tab, scroll to the Developer Token section near the bottom.
3. Click Generate Developer Token. Copy the 32-char token.
4. Paste into your .env.development:
   BOX_DEVELOPER_TOKEN=...
   
5. Run any of the examples in examples/typescript/box/.

​

Setup (long-running OAuth flow)

​

1. Create a Box App

1. Go to https://app.box.com/developers/console
2. Click Create New App
3. Choose Custom App
4. Authentication Method: User Authentication (OAuth 2.0)
5. Name it (e.g. “Mirage”) -> Create App

​

2. Configure the App

• OAuth 2.0 Redirect URIs: add every destination you’ll redirect back to. Box accepts multiple values, register them all up front so you don’t bounce between dev and prod:
  • For the CLI flow below: http://localhost:1
  • For the browser PKCE example: http://localhost:5173/box_pkce.html
  • For production: e.g. https://yourapp.com/box/callback
• Allowed Origins (only needed if you’ll call from a browser; older Box docs call this “CORS Domains”):
  • http://localhost:5173
  • Any production origins (e.g. https://yourapp.com)
• Application Scopes:
  • Read all files and folders stored in Box (required)
  • Write all files and folders stored in Box (only if you’ll add write commands later)
• Click Save Changes

​

3. Submit for Authorization (enterprise apps only)

​

4. Copy the Client Credentials

• Client ID -> BOX_CLIENT_ID
• Client Secret -> BOX_CLIENT_SECRET (skip if you only need PKCE)

​

5. Get the Refresh Token (CLI flow with client secret)

https://account.box.com/api/oauth2/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost:1

curl https://api.box.com/oauth2/token \
  -d "code=THE_CODE" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=http://localhost:1"

{
  "access_token": "T...",
  "expires_in": 3884,
  "refresh_token": "R...",
  "restricted_to": [],
  "token_type": "bearer"
}

​

6. Set Environment Variables

# .env.development
BOX_CLIENT_ID=...
BOX_CLIENT_SECRET=...
BOX_REFRESH_TOKEN=...

​

Alternative: PKCE Flow (browser, no client secret)

1. Add http://localhost:5173/box_pkce.html to OAuth 2.0 Redirect URIs
2. Add http://localhost:5173 to Allowed Origins
3. Set only BOX_CLIENT_ID in .env.development
4. From examples/typescript/browser/, run pnpm dev
5. Open http://localhost:5173/box_pkce.html and click Connect Box

​

Token Lifetime

• 60 days pass without use
• The user revokes the app at https://app.box.com/account/security
• The Box account password changes
• A new refresh token is issued (the old one expires after a short grace period)

​

CORS Notes

​

Troubleshooting

import { BoxResource } from '@struktoai/mirage-node'

const box = new BoxResource({
  clientId: process.env.BOX_CLIENT_ID!,
  clientSecret: process.env.BOX_CLIENT_SECRET!,
  refreshToken: process.env.BOX_REFRESH_TOKEN!,
})

import { BoxResource } from '@struktoai/mirage-browser'

const box = new BoxResource({
  clientId: 'YOUR_CLIENT_ID',
  refreshToken: refreshTokenFromLocalStorage,
  onRefreshTokenRotated: (next) => localStorage.setItem('box-refresh', next),
})