Skip to content
Try for free
On this page

Box

Box service accounts

Set up a Box Platform app with Client Credentials Grant so your workflows can use Box through its Service Account

Connect a Box Platform app using Client Credentials Grant. A Box admin authorizes the app, and Sim uses its Client ID, client secret, and Enterprise ID to obtain access tokens for the app's Service Account.

Prerequisites

Anyone with Developer Console access can create the app, but a Box admin or co-admin must authorize it in the Admin Console before it can mint tokens. Free developer accounts are authorized automatically.

Set up the platform app

1. Create the app

  1. Open the Box Developer Console, choose New App → Server, leave Client Credentials Grant selected, and create the app. Older consoles may label this Create Platform App → Server Authentication (with Client Credentials Grant)

  2. On the Configuration tab, set the App Access Level. App Access Only (the default) is sufficient — App + Enterprise Access and Generate User Access Tokens are needed to authenticate as managed users, but Sim’s saved connection authenticates as the Service Account and does not impersonate those users

  3. Under Application Scopes, check Read all files and folders stored in Box and Write all files and folders stored in Box. If you'll use Sim's Box Sign operations, also check Manage signature requests

  4. Copy the Client ID and Client secret from Configuration → OAuth 2.0 Credentials (Box requires multi-factor authentication before showing the secret)

  5. Copy the Enterprise ID — a numeric value. In the Developer Console, click your account icon in the top right and choose Copy Enterprise ID; a Box admin can also find it in Admin Console → Account & Billing → Account Information

2. Authorize the app in the Admin Console

Token requests fail with unauthorized_client ("This app is not authorized by the enterprise admin") until a Box admin authorizes the app:

  1. A Box admin or co-admin opens Admin Console → Apps → Platform Apps Manager (in some tenants this appears as Platform → Platform Apps)

  2. Click Add App and enter the app's Client ID

Alternatively, the developer can click Review and Submit on the app's Authorization tab in the Developer Console to send the request to the admin.

3. Give the service account access to folders

The Service Account is a brand-new Box user — its email looks like AutomationUser_AppServiceID_RandomString@boxdevedition.com and is shown on the app's General Settings tab. Its folder tree starts empty: a fully valid credential sees zero items and gets 404s on real files and folders until you grant it access.

  1. In Box, invite the Service Account's @boxdevedition.com email as a collaborator on each folder your workflows should work with — use the Editor role for read/write access

  2. Verify by running Sim's Box List Folder Items on folder ID 0 — the collaborated folders should appear

Invite the Service Account into specific folders rather than relying on access to another user’s root folder.

Add the service account to Sim

  1. Open Integrations from your workspace sidebar

  2. Search for "Box" and open it, then click Add to Sim and choose Add service account

  3. In the Add Box service account dialog, paste the Client ID, Client secret, and Enterprise ID (numeric), and optionally set a display name and description

  4. Click Add service account. Sim verifies the credentials by minting a real access token from Box — if it fails, the error tells you whether Box rejected the credentials or couldn't be reached. A rejection usually means bad credentials, an app the admin hasn't authorized yet, or values that don't all belong to the same app and enterprise.

Use the service account in workflows

Add a Box block to your workflow. In the credential dropdown, your Box service account appears alongside any OAuth credentials. Configure the operation and its required fields.

The block calls api.box.com with an access token minted for the Service Account. Operations are subject to the app's scopes and the folders the Service Account can see.

Sim's Box block includes Box Sign operations. These need the Manage signature requests scope on the app and Box Sign enabled on your enterprise's plan — without either, signature operations fail while file and folder operations keep working.

Token behavior

Access tokens minted from the app are short-lived (typically one hour) and there is no refresh token — Sim simply mints a new token when one is needed. The stored Client ID, secret, and Enterprise ID stay valid until you rotate the secret in the Developer Console or the admin removes the app's authorization. If you rotate the secret, update the credential in Sim right away — reconnecting asks you to re-enter all three values.

Handle connection and operation errors

SymptomCheck
Credential connects, but a file is missing or returns 404Invite the Service Account as a collaborator on the specific folder. A valid token does not grant access to another user’s content.
This app is not authorized by the enterprise adminHave an admin or co-admin authorize the app’s Client ID in Platform Apps Manager.
The grant type is unauthorized for this client_idConfirm that the app uses Server Authentication with Client Credentials Grant, rather than user authentication.
Grant credentials are invalidRe-copy the Client ID, secret, and Enterprise ID from the same app and enterprise, and confirm authorization.
A newly added scope still returns 403Re-authorize the app after changing its scopes or access level.
Box Sign alone failsConfirm Manage signature requests, re-authorization, and Box Sign availability on the enterprise plan.

See Box’s Client Credentials Grant setup. Sim reports a general authentication error for rejected token requests; the underlying cause may require checking Box’s app configuration.

Was this helpful?
Suggest an edit