Skip to main content

​
Overview

The Box integration lets Grady work in your Box content: browsing folders, reading file metadata, searching across file content, pulling files into a working session, filing new documents, and creating folders. Access works the way Box access already works for people. Gradial connects as a dedicated Box service account, and that account sees nothing until a Box admin invites it as a collaborator on a folder. Its reach is exactly the folders it’s been invited to — enforced by Box itself.
Access: Must be enabled for your organization. Contact your Gradial team to get access.

​
Why use Gradial with Box

  • Grady finds things by meaning — full-text search across file content, not just names
  • Documents become inputs — read a contract, compare two PDFs, extract data from a deck
  • Box becomes a destination — generated documents get filed into the right folder
  • Access stays in Box’s hands — you grant and revoke Grady’s reach with the same collaborator controls you already use, no separate permission model to maintain

​
What Grady can do

​
What Grady can never do

Deletion, moving, copying, sharing, shared-link creation, and collaboration changes do not exist in the integration — not as blocked actions, but as operations with no implementation. There is no way to phrase a request that removes, relocates, or externally shares a Box file through Grady. Uploads and folder creation also never overwrite. If something with the same name already exists, the operation fails rather than replacing what’s there.

​
How access works

This is the most important thing to understand about the Box integration, and the step teams most often miss.
1

Gradial connects as a Box service account

The connection uses a Box Platform App, which acts as its own Box user — not as the person who set it up. That account has a login like AutomationUser_…@boxdevedition.com.
2

The service account starts with access to nothing

Freshly connected, it can see no files and no folders. It is not an admin account and it does not inherit anyone’s access.
3

A Box admin invites it as a collaborator

To give Grady access to a folder, a Box admin invites the service account to that folder as a collaborator — exactly as they would invite a colleague. Grady’s reach is then that folder and everything beneath it.
Because Box enforces this boundary itself, Grady’s access is always visible and auditable where your team already looks: the folder’s collaborator list in Box. Removing the collaborator revokes Grady’s access immediately.
Content the service account isn’t collaborated on is reported by Box as simply not existing — so Grady can’t confirm or deny whether a file is there, let alone read it.

​
Before you start

You’ll need two people (or one person with both roles):
  • A Gradial organization admin — connecting an integration requires the Manage settings permission in Gradial
  • A Box administrator — authorizing the Platform App happens in the Box Admin Console and is protected by two-factor authentication
And from Box, three values:
  • Client ID
  • Client Secret
  • Enterprise ID
The Box Platform App must be authorized in the Box Admin Console with the Read and write all files and folders application scope before the connection will work. Authorizing the app does not by itself give Grady access to any content — collaboration invites still control that.

​
Connect Box

1

Create and authorize the Box Platform App

A Box admin creates a Box Platform App using client-credentials (server) authentication, then authorizes it in the Box Admin Console with the Read and write all files and folders scope. Collect the app’s Client ID, Client Secret, and your Enterprise ID.
2

Connect Box in Gradial

In Gradial, go to Settings → Integrations → Connect Integration → Box, then paste the Client ID, Client Secret, and Enterprise ID.Gradial verifies the credentials against Box before saving anything. If they’re wrong, or the app hasn’t been authorized in the Admin Console, the connection is rejected at this point rather than failing silently later.
3

Copy the service account login

Once connected, the Box integration row shows the Service account login. This is the Box user your admin needs to invite as a collaborator. Copy it.You can also ask Grady for it at any time — it will report the connected service account’s identity.
4

Invite the service account to the folders Grady should use

In Box, for each folder you want Grady to work in:
  1. Open the folder and invite a collaborator
  2. Paste the service account login
  3. Choose a permission level — Viewer for read-only work; Editor (or another level with upload rights) if Grady should file documents there
  4. Send the invite
Grady’s access begins at the folders you invite it to and extends to everything beneath them. Start with the narrowest folders that cover the work.
5

Assign the integration to an Environment

Go to Settings → Environments, select the Environment you want Box available in, and add the Box integration to it. This makes it available to all Workspaces in that Environment. Repeat for any other Environments that need it.
If a Workspace isn’t seeing Box, check this first — an unassigned integration is the most common cause.

​
Rotating credentials

Box credentials are rotated by connecting Box again from the integration catalog. Gradial verifies the new credentials and swaps them in a single step, so there’s no window where the connection is half-updated. There is no separate edit form — this is deliberate, because it guarantees new credentials are always verified before they take effect.

​
Changing what Grady can reach

Add or remove collaborator invites in Box. Nothing needs to change in Gradial — the next thing Grady does reflects the current collaboration state.

​
Limits

  • Uploads are capped at 50 MB per file. This is a Box API limit on single-request uploads. Larger files aren’t yet supported.
  • Downloads are not artificially capped — they’re bounded only by Box’s own per-file maximum.
  • Nothing is overwritten. A name collision fails; Grady will report it rather than replacing the existing item.
  • Search results can lag. Box search is eventually consistent, so a document uploaded moments ago may not appear in search yet. Browsing the folder shows it immediately.

​
Troubleshooting

​
Example prompts