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

# Box

> Connect Box, the cloud content management platform, to Serval so your workflows can manage Box Hubs, generate documents with Doc Gen, and administer your Box enterprise on demand.

## About Box

Box is a cloud content management platform for secure file storage, sharing, and governance. The Serval Box integration connects your Box account so workflows can work with Box Hubs, Box Doc Gen, and enterprise administration settings live, as they run. Box currently carries a **Beta** badge in the Serval app catalog.

**Authentication:** Two options - **Sign in with Box** (OAuth 2.0, labeled Recommended), which uses a Serval-managed Box app with selectable permission presets, or **Client Credentials Grant**, which uses your own Box Platform App and authenticates as your enterprise's Service Account or as a specific Box user.

**Data sync:** On-demand only. Connecting Box installs no workflows and no scheduled syncs - workflows call the Box API live (all traffic goes to api.box.com). Sign in with Box connections refresh their access token automatically as it nears expiry; Client Credentials connections mint a fresh short-lived token on every request, because Box issues no refresh tokens for that grant type.

## What the Box integration enables

| Capability                | Description                                                                                                                                                                                                                                                                                               |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Generic Box API access    | Workflows can reach any part of the Box API through a single Serval-managed action, with authentication handled for you.                                                                                                                                                                                  |
| Box Hubs                  | List, create, get, update, copy, and delete Box Hubs; add and remove Hub items; list enterprise Hubs; and manage Hub collaborations for users and groups.                                                                                                                                                 |
| Box Doc Gen               | Mark files as Doc Gen templates, list templates and template tags, generate documents in batches, and track Doc Gen jobs by job, template, or batch.                                                                                                                                                      |
| Enterprise administration | Read enterprise configuration (security, content and sharing, user settings, shield); manage shield lists; create, update, and delete archives; and submit external-user deletion jobs.                                                                                                                   |
| OAuth permission presets  | Connect-time checkboxes that map to [Box scopes](https://developer.box.com/guides/api-calls/permissions-and-errors/scopes): Read Files and Folders (checked by default), Read and Write Files and Folders, Manage Users, Manage Groups, Manage Webhooks, Enterprise Administration, Box Sign, and Box AI. |

Anything defined in the [Box API](https://developer.box.com/reference) can be accessed through Serval.

## Get your credentials

Which setup you need depends on the connection method you choose. **Sign in with Box** requires nothing created on the Box side - Serval uses its own managed Box app and you simply sign in and approve. **Client Credentials Grant** requires a Box Platform App that you create and a Box admin authorizes; see the [Box Client Credentials Grant guide](https://developer.box.com/guides/authentication/client-credentials/) for background.

<Tabs>
  <Tab title="Sign in with Box (OAuth 2.0)">
    No credentials to create. You will sign in with your Box account and choose permission presets directly in the Serval connect dialog.

    <Note>
      Effective permissions are capped by what your Box account can do, and the presets you pick are fixed at connect time. Choose the presets your workflows will need before you authorize - changing them later means reconnecting.
    </Note>
  </Tab>

  <Tab title="Client Credentials Grant (Custom App)">
    <Steps>
      <Step title="Create a Box Platform App">
        Go to the [Box Developer Console](https://app.box.com/developers/console), open **Platform Apps**, and click **New App**. Enter an app name and select **Client Credentials Grant** as the app type. Box does not let you change an app's authentication method later, so pick Client Credentials Grant from the start.
      </Step>

      <Step title="Set access level and Application Scopes">
        In the app's **Configuration** tab, set the **App Access Level** and enable the **Application Scopes** your workflows need, then save your changes. With this method, permissions live on the Box app, not in Serval.

        <Note>
          If you plan to connect as a specific Box user rather than the Service Account, also enable **App + Enterprise Access** and **Generate User Access Tokens** on the Configuration tab - Box will not issue user tokens without them.
        </Note>
      </Step>

      <Step title="Copy the Client ID and Client Secret">
        Both are on the **Configuration** tab.

        <Note>
          Box requires two-factor authentication on your account before it will reveal the Client Secret.
        </Note>
      </Step>

      <Step title="Have a Box admin authorize the app">
        On the app's **Configuration** tab, a Box Admin or Co-Admin can click **Authorize** directly; anyone else clicks **Submit** to send an authorization request. Admins manage approvals in the Box Admin Console under **Integrations**, then [**Platform Apps Manager**](https://app.box.com/master/platform-apps).

        <Warning>
          Until an admin authorizes the app, Box rejects its credentials and the Serval connection cannot be saved.
        </Warning>
      </Step>

      <Step title="Find your Enterprise ID (or User ID)">
        Your Enterprise ID is shown in the Box Admin Console under **Account & Billing**. If you plan to connect as a specific Box user instead of the Service Account, note that user's Box User ID from the Admin Console's **Users & Groups** page. See [Box user types](https://developer.box.com/platform/user-types) for the difference.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Connect in Serval

<Tabs>
  <Tab title="Sign in with Box (OAuth 2.0)">
    <Steps>
      <Step title="Add Box from the app catalog">
        Find **Box** (shown with a Beta badge) and start a new connection. The **Connect Box** dialog opens with the two connection methods.
      </Step>

      <Step title="Choose Sign in with Box">
        It is labeled **Recommended** in the method selection dialog.

        <Note>
          This option only appears when platform integration OAuth is enabled for your organization. If it is not, the dialog opens directly on the Client Credentials Grant form instead.
        </Note>
      </Step>

      <Step title="Pick permission presets">
        **Read Files and Folders** is checked by default. Check any additional presets your workflows need - they are fixed once you authorize.
      </Step>

      <Step title="Sign in and approve">
        Click **Connect Account** and complete the Box sign-in and consent screen. Serval then names the connection after your Box enterprise; personal (non-enterprise) Box accounts are supported too, in which case the connection is named after your email domain.
      </Step>
    </Steps>

    <Tip>
      After connecting, the connection's settings page lists the permissions Box actually granted under **Current Scopes** and offers a **Reconnect** button for re-running the flow with different presets.
    </Tip>
  </Tab>

  <Tab title="Client Credentials Grant (Custom App)">
    <Steps>
      <Step title="Add Box from the app catalog">
        Find **Box** (shown with a Beta badge), start a new connection, and choose the Client Credentials Grant method. The dialog title changes to **Configure Box**.
      </Step>

      <Step title="Instance Name (optional)">
        Placeholder: "e.g., My Box Integration". If left blank, Serval names the connection "Box (enterprise)" or "Box (user)" based on your Subject Type.
      </Step>

      <Step title="Client ID (required)">
        Placeholder: "From Box Developer Console". Paste the Client ID from your app's Configuration tab.
      </Step>

      <Step title="Client Secret (required)">
        Placeholder: "From Box Developer Console". Paste the Client Secret. This is a password field.
      </Step>

      <Step title="Subject Type (required)">
        A dropdown with exactly two options: **Enterprise (Service Account)** and **User**. It defaults to Enterprise. Helper text: "Enterprise authenticates as the app's Service Account. User authenticates as a specific Box user."
      </Step>

      <Step title="Enterprise/User ID (required)">
        Placeholder: "Your Box Enterprise ID or User ID". Helper text: "Enter your Enterprise ID if using Enterprise subject type, or the User ID if using User subject type."
      </Step>

      <Step title="Save the connection">
        Click **Submit**. Serval validates your credentials by fetching a real token from Box before the connection is created. If any required field is blank, the form blocks submission with "Please fill in all required fields". If Box rejects the credentials, the dialog shows an error beginning with "Failed to install integration" followed by the specific reason - see the troubleshooting section below for the most common causes.
      </Step>
    </Steps>

    <Tip>
      To edit a Client Credentials connection later, open the connection's settings page and click **Reconnect**. The Configure Box form opens prefilled with your saved values, with the Client Secret masked. Leave the masked value to keep your existing secret, or paste a new one to replace it; any field you change is validated with a live token fetch from Box before it is saved, and fields you leave alone keep their stored values.
    </Tip>
  </Tab>
</Tabs>

## Verifying the connection

Box does not surface named health checks in Serval - the **Health Checks** section that appears on some integrations' settings pages is not shown for Box, and there is no built-in connection test with success or failure messages. The most direct way to confirm the connection works end to end is to run a quick read-only workflow against Box - for example, one that lists your Box Hubs - and check that it returns data. Your Serval team or Catalyst can set one up in a couple of minutes.

For Sign in with Box connections, the settings page also lists the permissions the connection holds under **Current Scopes** - the fastest way to confirm the right presets were granted.

<Tip>
  A working token does not mean every workflow will succeed. The most common follow-on failure is a permissions gap: for Sign in with Box connections, a preset you did not check at connect time; for Client Credentials connections, an Application Scope not enabled (and saved) on the app in the Box Developer Console, or content the Service Account has never been invited to.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Connecting fails after I submit my Client Credentials">
    Serval mints a real token from Box before saving the connection, and when Box rejects the attempt the dialog shows the reason - an error beginning with "Failed to install integration" that includes "Box rejected the credentials" and the detail Box returned. The most common cause is an app no Box admin has authorized yet: submit it from its **Configuration** tab and have an admin approve it in the [Box Admin Console's Platform Apps Manager](https://app.box.com/master/platform-apps), then try again. A wrong Enterprise ID or User ID, a Subject Type that does not match the ID you entered, or a rotated Client Secret all fail the same way.
  </Accordion>

  <Accordion title="Connected as Enterprise but workflows can't see anyone's files">
    With Subject Type **Enterprise**, calls run as the app's Service Account - a separate identity with its own folder tree. It sees no user content unless that content is explicitly shared (collaborated) with it. Either collaborate the Service Account into the folders you need, or connect with Subject Type **User** as a specific Box user - which additionally requires **App + Enterprise Access** and **Generate User Access Tokens** enabled on the app's Configuration tab. See [Box user types](https://developer.box.com/platform/user-types).
  </Accordion>

  <Accordion title="I need different permissions on a Sign in with Box connection">
    OAuth permissions are fixed at connect time: Serval requests read access to files and folders by default plus whichever presets you checked, and records what Box actually granted. To change permissions, open the connection's settings page, review **Current Scopes**, and click **Reconnect** to re-run the flow with new presets. Permissions are always capped by what the authorizing Box user can do.
  </Accordion>

  <Accordion title="Rotating the Client Secret or changing the subject on an existing connection">
    Open the connection's settings page and click **Reconnect**. The Configure Box form opens prefilled with the saved Instance Name, Client ID, Subject Type, and Enterprise/User ID, and the Client Secret shown as a masked placeholder. Paste a new secret to rotate it, or leave the masked value untouched to keep the existing one - the helper text under the field says exactly that. Submitting validates the resulting credentials with a live token fetch from Box; if Box rejects them, the dialog shows an error beginning with "Failed to update integration" and nothing is overwritten.
  </Accordion>

  <Accordion title="Workflow runs fail with a Box authentication error">
    If token minting fails during a workflow request on a Client Credentials connection, the run shows: "Box authentication failed for '\[instance name]'. Please verify your credentials in Box Developer Console. Error: \[details]". Check that the app is still authorized by your Box admin and that its Client Secret has not been rotated; if the secret changed, click **Reconnect** on the connection's settings page and paste the new value.
  </Accordion>

  <Accordion title="Some Box operations aren't in the typed catalog">
    Workflows reach Box through a single Box API request action. Its typed, documented catalog covers Box's v2025.0 endpoint set: Hubs, Doc Gen, enterprise configuration, shield lists, archives, and external-user deletion jobs. Classic Box operations such as listing a folder's items are not part of the typed catalog, but the same action can still call them - every request to Box's official API address is authenticated automatically.
  </Accordion>

  <Accordion title="Box shows a Beta badge in the catalog">
    The Box integration is currently flagged Beta, so it appears with a Beta badge in the Serval app catalog. It is fully connectable; the badge reflects the integration's maturity status.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Box integration.