> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gradial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Box

> Connect Box so Grady can search, read, download, and file documents — scoped to exactly the folders a Box admin shares with it, and never able to delete.

## 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.

<Info>
  **Access:** Must be enabled for your organization. Contact your Gradial team to get access.
</Info>

### 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

| Capability          | What it means                                                                  |
| ------------------- | ------------------------------------------------------------------------------ |
| **Identify itself** | Report the service account login a Box admin needs to invite as a collaborator |
| **Browse**          | Page through a folder's files and subfolders                                   |
| **Read metadata**   | File name, size, checksum, parent folder, and timestamps                       |
| **Search**          | Full-text search over file names and content, optionally scoped to a subtree   |
| **Download**        | Pull a file into the working session to read, parse, compare, or migrate       |
| **Upload**          | File a document from the working session into a Box folder                     |
| **Create folders**  | Add a folder inside a folder it can write to                                   |

### 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.

<Steps>
  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Tip>
  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.
</Tip>

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**

<Note>
  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.
</Note>

***

## Connect Box

<Steps>
  <Step title="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**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.

    <Note>
      If a Workspace isn't seeing Box, check this first — an unassigned integration is the most common cause.
    </Note>
  </Step>
</Steps>

### 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

| What you see                                     | What it means                                                                                                                                                                                             |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Grady says an item can't be found**            | Almost always "not collaborated." Box reports content the service account can't reach as nonexistent. Invite the service account to the folder in Box.                                                    |
| **Grady can read but not upload**                | The service account's collaborator role on that folder is read-only. Raise it to a role with upload rights.                                                                                               |
| **A just-uploaded file isn't in search results** | Box search indexing lag. Browse the folder instead — the file is there.                                                                                                                                   |
| **An upload fails on the name**                  | Something with that name already exists. Grady never overwrites; choose a different name or work with the existing file.                                                                                  |
| **Box is throttling requests**                   | Box rate-limits heavy activity. Grady waits and retries as Box directs.                                                                                                                                   |
| **The connection is reported as broken**         | The service-account credentials are no longer valid — for example the Platform App's authorization was revoked in the Box Admin Console. A Gradial admin reconnects Box from **Settings → Integrations**. |
| **A Workspace can't use Box**                    | The integration isn't assigned to that Workspace's Environment.                                                                                                                                           |

***

## Example prompts

```
Find every PDF in our Box product-launch folder that mentions the old tagline.
```

```
Compare the two contract PDFs in Box under Legal/Vendor Agreements and tell me
what changed.
```

```
Write the Atlas launch summary as a Word document and upload it to our Box
launch folder.
```

```
Pull the approved hero images out of Box and upload them to AEM.
```

***

## Related

* [SharePoint →](/docs/integrations-administration-and-setup/integrations/sharepoint) — the same document workflows, with a folder allow-list access model
* [Office Docs →](/docs/campaign-management/office-docs) — how Gradial creates and works with Word, Excel, and PowerPoint files
* [Digital Asset Management →](/docs/asset-management/digital-asset-management)
* [Integrations Overview →](/docs/integrations-administration-and-setup/integrations/get-started-with-integrations)