# Box service accounts (/integrations/box-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 [#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 [#setting-up-the-platform-app]

### 1. Create the app [#1-create-the-app]

<Steps>
  <Step>
    Open the [Box Developer Console](https://app.box.com/developers/console), choose **New App → Server**, leave **Client Credentials Grant** selected, and create the app. Older consoles may label this &#x2A;*Create Platform App → Server Authentication (with Client Credentials Grant)**
  </Step>

  <Step>
    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
  </Step>

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

  <Step>
    Copy the **Client ID** and **Client secret** from **Configuration** → **OAuth 2.0 Credentials** (Box requires multi-factor authentication before showing the secret)
  </Step>

  <Step>
    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**
  </Step>
</Steps>

### 2. Authorize the app in the Admin Console [#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:

<Steps>
  <Step>
    A Box admin or co-admin opens **Admin Console** → **Apps** → **Platform Apps Manager** (in some tenants this appears as **Platform** → **Platform Apps**)
  </Step>

  <Step>
    Click **Add App** and enter the app's **Client ID**
  </Step>
</Steps>

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.

<Callout type="warn">
  **Authorization is a snapshot.** If you later change the app's scopes or access level — for example, adding the signature scope — the admin must **re-authorize** the app in the same Platform Apps Manager section before the change takes effect. Until then, token minting keeps succeeding but the new scopes don't apply, which surfaces as persistent `403` errors on tools despite correct-looking configuration.
</Callout>

### 3. Give the service account access to folders [#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 `404`s on real files and folders until you grant it access.

<Steps>
  <Step>
    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
  </Step>

  <Step>
    Verify by running Sim's Box **List Folder Items** on folder ID `0` — the collaborated folders should appear
  </Step>
</Steps>

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

## Add the service account to Sim [#adding-the-service-account-to-sim]

<Steps>
  <Step>
    Open **Integrations** from your workspace sidebar
  </Step>

  <Step>
    Search for "Box" and open it, then click **Add to Sim** and choose **Add service account**
  </Step>

  <Step>
    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
  </Step>

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

## Use the service account in workflows [#using-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 [#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 [#handle-connection-and-operation-errors]

| Symptom | Check |
| - | - |
| Credential connects, but a file is missing or returns `404` | Invite 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 admin` | Have an admin or co-admin authorize the app’s Client ID in Platform Apps Manager. |
| `The grant type is unauthorized for this client_id` | Confirm that the app uses Server Authentication with Client Credentials Grant, rather than user authentication. |
| `Grant credentials are invalid` | Re-copy the Client ID, secret, and Enterprise ID from the same app and enterprise, and confirm authorization. |
| A newly added scope still returns `403` | Re-authorize the app after changing its scopes or access level. |
| Box Sign alone fails | Confirm **Manage signature requests**, re-authorization, and Box Sign availability on the enterprise plan. |

See Box’s [Client Credentials Grant setup](https://developer.box.com/guides/authentication/client-credentials/client-credentials-setup/). Sim reports a general authentication error for rejected token requests; the underlying cause may require checking Box’s app configuration.