Skip to main content

​
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 folders, files, collaborations, users, and groups, plus Box Hubs, Box Doc Gen, and enterprise administration settings live, as they run. 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: Workflows call the Box API live, on demand (all traffic goes to api.box.com). One scheduled sync exists, opt-in per connection: knowledge sync, which ingests documents from the folders you explicitly select as knowledge. 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

Anything defined in the Box API 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 for background.
No credentials to create. You will sign in with your Box account and choose permission presets directly in the Serval connect dialog.
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.

​
Connect in Serval

1

Add Box from the app catalog

Find Box and start a new connection. The Connect Box dialog opens with the two connection methods.
2

Choose Sign in with Box

It is labeled Recommended in the method selection dialog.
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.
3

Pick permission presets

Read Files and Folders is checked by default. Check any additional presets your workflows need - they are fixed once you authorize.
4

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

​
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 the items in a folder - 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.
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.

​
Gotchas and troubleshooting

Serval mints a real token from Box before saving the connection, and when Box rejects the attempt the dialog shows the reason - an error that includes “failed to validate Box 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, 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.
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.
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.
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. 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.
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.
Workflows reach Box through a single Box API request action. Its typed, documented catalog covers the classic endpoints for folders, files, collaborations, search, users, and groups, plus Box’s 2025.0 endpoint set: Hubs, Doc Gen, enterprise configuration, shield lists, archives, and external-user deletion jobs. Operations beyond that - for example metadata templates, webhooks, or Box Sign requests - are not yet callable from workflows; contact Serval if you need one and we can extend the catalog.
Need help? Contact support@serval.com for assistance with your Box integration.