Box Integration for AI Agents

The real problem

Why this is harder than it looks

The Box API is clean and the OAuth 2.0 flow is standard. A working single-user prototype takes an afternoon. The complexity arrives when you try to do this for real users in a multi-tenant product.

Box's OAuth scopes are not fine-grained by default — granting _{root_readwrite} gives your agent full read-write access to everything the user owns. In enterprise Box deployments, admins can restrict which OAuth apps are allowed to connect via Box's application approval process. If your OAuth app isn't explicitly approved in their Box Admin Console, your authorization flow silently fails after the redirect. There's no OAuth error — the user just doesn't land back in your app. Debugging this requires knowing to look at Box Admin Console → Apps → Custom Apps, which most developers find only after hours of investigation.

Then there's the token lifecycle. Box access tokens expire after 60 minutes. Refresh tokens last 60 days but are single-use — every refresh issues a new refresh token that must be stored, replacing the old one. If two concurrent requests trigger a refresh race, one will succeed and the other will invalidate a now-stale token, leaving that user's session broken until they re-authorize. In a multi-tenant system, you need per-user token storage with atomic refresh logic, or you'll see intermittent auth failures that are nearly impossible to reproduce.

Finally, Box requires you to register your own OAuth app — there is no shared developer app you can use for production. Every deployment needs a Box Connected App with its own Client ID and Secret, which means your onboarding process must handle credential collection before any user can authorize.

Scalekit handles token storage, atomic refresh, and per-user isolation. Your agent names a tool and passes parameters. The auth plumbing is not your problem.

Capabilities

What your agent can do with Box

Once connected, your agent has 79 pre-built tools covering the full Box API surface:

• Browse and manage files and folders: list folder contents, get file details, copy, move, rename, and delete files and folders end-to-end
• Search across the entire Box instance: full-text search with type, extension, date range, and folder scope filters
• Create and assign tasks: attach review or completion tasks to files, assign them to users, and track resolution state
• Share files and folders: create shared links with configurable access levels, download permissions, passwords, and expiry dates
• Manage collaborations: grant and revoke user or group access to specific files and folders with role-based permissions
• Manage users, groups, and enterprise metadata: create and update users, manage group memberships, apply metadata templates, and stream enterprise events

Jump to full tool reference

Setup context

What we're building

This guide connects a document operations agent to Box — helping teams search content, manage file workflows, assign review tasks, and control sharing permissions without leaving your product.

Setup

¹ Setup: One SDK, One credential

Install the Scalekit SDK. The only credential your application manages is the Scalekit API key — no Box secrets, no user tokens, nothing belonging to your users.

Connected Accounts

² Per-User Auth: Creating connected accounts

Each user gets their own Connected Account, giving them a dedicated auth context. The _identifier is any unique string from your system — a UUID, email, whatever you use internally.

This call is idempotent — safe to call on every session start. Returns the existing account if one already exists.

Authorization Flow

³ The authorization flow

The user authorizes your agent once. Scalekit generates the OAuth URL with correct scopes, PKCE challenge, and redirect handling pre-configured. After approval, you never see the token.

Calling Box

⁴ Calling Box: What your agent writes

With the connected account active, your agent calls Box actions using _{actions.execute_tool()}. Name the tool, pass parameters. Scalekit handles token retrieval and request construction.

List folder contents

Start here to discover file and folder IDs. Pass _"0" for the root folder. Use _limit and _offset for pagination.

Search files and folders

Search using a query string. Scope to a specific folder with _{ancestor_folder_ids}, filter by file type, extension, or date range. Returns up to 200 results per call.

Create a task and assign it

Attach a review task to a file, then assign it to a user. The task _action can be _review or _complete. Use the task ID from the first call in the assignment.

Create a shared link for a file

Generate a shared link with access level, download permission, and optional expiry. _access can be _open, _company, or _{collaborators}.

Framework wiring

⁵ Wiring into your agent framework

Scalekit integrates directly with LangChain. The agent decides what to call; Scalekit handles auth on every invocation. No token plumbing in your agent logic.

Tool reference

All 79 Box tools

Grouped by capability. Your agent calls tools by name — no API wrappers to write.

Connector notes

Box-specific behavior

Infrastructure decision

Why not build this yourself

The Box OAuth flow is documented. Token storage isn't technically hard. But here's what you're actually signing up for:

That's one connector. Your agent product will eventually need Salesforce, Gmail, Slack, Notion, and whatever else your customers ask for. Each has its own OAuth quirks and failure modes.

Scalekit maintains every connector. You maintain none of them.