Skip to content

Authentication

Jump to bottom
mrdulasolutions edited this page May 25, 2026 · 2 revisions

Authentication

How agents authenticate to Box.

The cloud plugin itself doesn't manage auth — it invokes whatever Box MCP your agent runtime has connected. But for users building outside Claude Code / Cowork, or doing custom integrations, the auth choice matters.

Auth modes Box supports

Mode Best for How it works
Client Credentials Grant (CCG) Headless / service-account agents Server-to-server, no user in loop. Box recommends this for agent workflows.
OAuth 2.0 (Authorization Code) Per-user agents Agent acts as the logged-in user. Used by the official Box remote MCP.
JWT Legacy enterprise integrations Works but more complex (keypair rotation). Use CCG instead for new builds.
Developer Token Local development / testing only 60-minute lifetime. Not for production.

Recommendation matrix

Scenario Recommended auth
Cowork / Claude Code user OAuth via Settings → Connectors → Box (Box's official remote MCP at mcp.box.com uses this)
Headless agent running on your server CCG
Multi-user agent platform (each call as the user) OAuth
CI / batch job CCG
LangChain / LlamaIndex integration in production CCG
Local dev iteration Developer Token (rotate to OAuth/CCG before deploy)

Why CCG for headless

CCG (Client Credentials Grant) is a service-account auth pattern:

  • No human in the loop
  • No token refresh juggling (Box issues new tokens automatically)
  • No keypair management like JWT
  • Box explicitly recommends CCG for OpenClaw-style agent workflows (Box blog post)

Setup:

  1. Create a Box App in the developer console
  2. Configure as Custom App → Server Authentication (Client Credentials Grant)
  3. Get Client ID + Client Secret
  4. Box admin authorizes the app for the enterprise
  5. Use the credentials in your agent runtime; tokens auto-refresh

Why OAuth for per-user

OAuth represents the user, not the application. Every API call is attributed to the authenticated user — audit logs, ACLs, and rate limits all follow them. This is what the official Box remote MCP uses.

Trade-off: needs the user to do an OAuth flow first. Not suitable for fully headless.

Why NOT JWT for new builds

JWT works but adds operational overhead:

  • Keypair generation and rotation
  • Token signing implementation
  • Subject claim management

CCG is the modern simpler equivalent. Switch to it for new builds.

Boxs SDKs and auth

Box's SDKs (v10) all support the four auth modes:

Language Repo Auth modes
Python box/box-python-sdk Dev Token, OAuth, JWT, CCG
Node.js box/box-node-sdk Dev Token, OAuth, JWT, CCG
Java box/box-java-sdk OAuth, JWT, CCG
.NET box/box-windows-sdk-v2 OAuth, JWT, CCG
iOS (Swift) box/box-ios-sdk OAuth

Use v10 — the older "Next-gen" generated SDKs were merged into v10 in Sept 2025.

How LangChain / LlamaIndex handle auth

Framework Auth modes
langchain-box Dev Token, JWT, CCG
llama-index-readers-box CCG, JWT, OAuth, Dev Token

CCG is the most common choice in both because it fits the typical retrieval / loader pattern (headless, recurring fetches).

Token scopes — same gotcha across modes

OAuth scopes (root_readwrite, ai.readwrite, docgen.readwrite) don't widen on Box tier upgrade. After a plan change, you must:

  1. Disconnect the Box MCP / OAuth integration
  2. Reconnect, granting any newly-needed scopes

See Operational Notes Note 2 for the diagnostic flow.

Using the plugin with non-Claude agent harnesses

Claude Code and Cowork handle Box OAuth transparently via Settings → Connectors → Box. Every other agent harness (Hermes, OpenClaw, Codex, Cursor, custom) requires manual setup because Box's OAuth server does not support Dynamic Client Registration (DCR).

If your harness tries to auto-register against mcp.box.com, you get 401. Box requires a pre-registered Box Custom App with client_id + client_secret.

The shape of the manual flow (any harness)

  1. Create a Box Custom App in the developer console

    • Custom App → User Authentication (OAuth 2.0)
    • Configuration → OAuth 2.0 Redirect URI: your harness's exact callback URI (varies — see per-harness section)
    • Configuration → Application Scopes: enable
      • Read/write all files (root_readwrite)
      • Manage enterprise properties (manage_enterprise_properties)
      • Manage AI (ai.readwrite)
    • Save and copy Client ID + Client Secret

  2. Configure your harness with the client_id, client_secret, and OAuth flag (see per-harness section).

  3. Trigger the OAuth flow once. Browser opens, Box login, click Authorize. Tokens cache and auto-refresh.

  4. Reload MCP in your harness so the session sees the new tool list.

The plugin's /box-mcp-check --harness=<name> skill walks you through the right flow per harness — invoke it when setup fails.

Hermes (verified working)

  • Redirect URI: http://127.0.0.1:8723/callback (exact)
  • Config file: ~/.hermes/config.yaml
  • Config block: 
    mcp_servers:
  box:
    url: https://mcp.box.com
    auth: oauth                # REQUIRED — see gotcha below
    oauth:
      client_id: <from Box app>
      client_secret: <from Box app>
      redirect_port: 8723

The auth: oauth silent-failure gotcha: without the top-level auth: oauth key, hermes mcp test box reports Auth: none and the server 401s — even though the oauth: credentials block parsed correctly. This is the #1 setup failure mode. If you see "Auth: none", add the auth: oauth line and re-run.

Post-OAuth reload: Hermes loads MCP tools at session start (for prompt caching). After OAuth succeeds, the box-* skills in your current session won't see the toolset until you start a new session (/new) or run /reload-mcp.

Verified: Hermes + Claude 4.7 + Box Custom App + 30 tools live (2026-05-25).

Generic (OpenClaw, Codex, Cursor, custom harnesses)

The dev-console setup is identical to Hermes. What changes per harness:

  1. Redirect URI — your harness's specific callback URI. Check harness docs.
  2. Config file location — ~/.<harness>/... typically; varies.
  3. Auth flag key — some harnesses require a separate auth: oauth (or equivalent) key. Always check.

/box-mcp-check --harness=generic asks you these three questions, then walks you through the rest.

For starting-point patterns per harness, see references/harness-oauth-setup.md in the repo.

Model floor for setup

The setup flow involves dev-console navigation, copying credentials, editing YAML/TOML config, parsing silent failure modes. Verified with Claude 4.5+. Weaker models may stall, especially on Hermes's auth: oauth silent failure.

Workaround for weak-model deployments: do the one-time setup in a Claude 4.5+ session, then any model can use the connection afterwards. Tokens persist in the harness config; the agent doesn't redo OAuth per session.

When to use this section vs the standard flow

  • Claude Code / Cowork users: ignore this section. Use Settings → Connectors → Box. The Anthropic-side Box integration handles OAuth.
  • Anyone else running Claude/another model in their own harness: read this. You're in DIY OAuth land.
  • Headless service-account agents: use CCG instead (see "Why CCG for headless" above) — no user OAuth flow needed.

See also

box-memory · MIT · Repo · Latest release · Issues · Air-gapped variant

Home

Getting started

Concepts

Features

Skills reference

Integrations

Operations

Project

Clone this wiki locally