|
| 1 | +--- |
| 2 | +title: Box Service Accounts |
| 3 | +description: Set up a Box Platform app with Client Credentials Grant so your workflows can use Box through its Service Account |
| 4 | +--- |
| 5 | + |
| 6 | +import { Callout } from 'fumadocs-ui/components/callout' |
| 7 | +import { Step, Steps } from 'fumadocs-ui/components/steps' |
| 8 | +import { FAQ } from '@/components/ui/faq' |
| 9 | + |
| 10 | +Box Platform apps with **Server Authentication (with Client Credentials Grant)** let your workflows authenticate to Box as the app's own **Service Account** instead of through a person's OAuth login. You create the app once, a Box admin authorizes it for the enterprise, and Sim mints short-lived access tokens from the app's credentials on demand — no user consent to expire, and access that's controlled entirely by which folders the Service Account is invited into. |
| 11 | + |
| 12 | +This is the recommended way to use Box in production workflows: nothing depends on a user staying logged in, the app's scopes are explicit, and the Service Account's reach is auditable folder by folder. |
| 13 | + |
| 14 | +## Prerequisites |
| 15 | + |
| 16 | +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. |
| 17 | + |
| 18 | +## Setting Up the Platform App |
| 19 | + |
| 20 | +### 1. Create the App |
| 21 | + |
| 22 | +<Steps> |
| 23 | + <Step> |
| 24 | + Go to the [Box Developer Console](https://app.box.com/developers/console), open **My Apps**, click **Create Platform App**, and choose **Server Authentication (with Client Credentials Grant)** |
| 25 | + |
| 26 | + {/* TODO(screenshot): Box Developer Console Create Platform App dialog with Server Authentication (with Client Credentials Grant) selected */} |
| 27 | + </Step> |
| 28 | + <Step> |
| 29 | + On the **Configuration** tab, set the **App Access Level**. **App Access Only** (the default) is sufficient — choose **App + Enterprise Access** only if the Service Account should also reach existing managed users' content via admin APIs |
| 30 | + </Step> |
| 31 | + <Step> |
| 32 | + 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** |
| 33 | + |
| 34 | + {/* TODO(screenshot): Application Scopes section with read, write, and signature scopes checked */} |
| 35 | + </Step> |
| 36 | + <Step> |
| 37 | + Copy the **Client ID** and **Client secret** from **Configuration** → **OAuth 2.0 Credentials** (revealing the secret may prompt for two-factor verification) |
| 38 | + |
| 39 | + {/* TODO(screenshot): OAuth 2.0 Credentials panel showing the Client ID and the client secret reveal */} |
| 40 | + </Step> |
| 41 | + <Step> |
| 42 | + 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** |
| 43 | + </Step> |
| 44 | +</Steps> |
| 45 | + |
| 46 | +### 2. Authorize the App in the Admin Console |
| 47 | + |
| 48 | +Token requests fail with `unauthorized_client` ("This app is not authorized by the enterprise admin") until a Box admin authorizes the app: |
| 49 | + |
| 50 | +<Steps> |
| 51 | + <Step> |
| 52 | + A Box admin or co-admin opens **Admin Console** → **Apps** → **Platform Apps Manager** (in some tenants this appears as **Platform** → **Platform Apps**) |
| 53 | + </Step> |
| 54 | + <Step> |
| 55 | + Click **Add App** and enter the app's **Client ID** |
| 56 | + |
| 57 | + {/* TODO(screenshot): Platform Apps Manager Add App dialog with the Client ID entered */} |
| 58 | + </Step> |
| 59 | +</Steps> |
| 60 | + |
| 61 | +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. |
| 62 | + |
| 63 | +<Callout type="warn"> |
| 64 | +**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. |
| 65 | +</Callout> |
| 66 | + |
| 67 | +### 3. Give the Service Account Access to Folders |
| 68 | + |
| 69 | +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. |
| 70 | + |
| 71 | +<Steps> |
| 72 | + <Step> |
| 73 | + 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 |
| 74 | + |
| 75 | + {/* TODO(screenshot): Box folder collaboration dialog inviting the AutomationUser email as Editor */} |
| 76 | + </Step> |
| 77 | + <Step> |
| 78 | + Verify by running Sim's Box **List Folder Items** on folder ID `0` — the collaborated folders should appear |
| 79 | + </Step> |
| 80 | +</Steps> |
| 81 | + |
| 82 | +<Callout type="info"> |
| 83 | +Community reports indicate the Service Account can't be collaborated into a user's root folder itself — invite it into individual folders instead. |
| 84 | +</Callout> |
| 85 | + |
| 86 | +## Adding the Service Account to Sim |
| 87 | + |
| 88 | +<Steps> |
| 89 | + <Step> |
| 90 | + Open **Integrations** from your workspace sidebar |
| 91 | + </Step> |
| 92 | + <Step> |
| 93 | + Search for "Box" and open it, then click **Add to Sim** and choose **Add service account** |
| 94 | + |
| 95 | + {/* TODO(screenshot): Box integration page with the Add service account connect option */} |
| 96 | + </Step> |
| 97 | + <Step> |
| 98 | + 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 |
| 99 | + |
| 100 | + {/* TODO(screenshot): Add Box service account dialog with all three fields filled in */} |
| 101 | + </Step> |
| 102 | + <Step> |
| 103 | + 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. |
| 104 | + </Step> |
| 105 | +</Steps> |
| 106 | + |
| 107 | +## Using the Service Account in Workflows |
| 108 | + |
| 109 | +Add a Box block to your workflow. In the credential dropdown, your Box service account appears alongside any OAuth credentials. Select it and configure the block as you normally would. |
| 110 | + |
| 111 | +{/* TODO(screenshot): Box block in a workflow with the Box service account selected as the credential */} |
| 112 | + |
| 113 | +The block calls `api.box.com` with a freshly minted access token — the same requests as the OAuth flow, so every Box operation works, subject to the app's scopes and the folders the Service Account can see. |
| 114 | + |
| 115 | +<Callout type="info"> |
| 116 | +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. |
| 117 | +</Callout> |
| 118 | + |
| 119 | +## Token Behavior |
| 120 | + |
| 121 | +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. |
| 122 | + |
| 123 | +<FAQ items={[ |
| 124 | + { question: "Why a Service Account instead of OAuth?", answer: "The Service Account is its own Box user, owned by the app — nothing expires when someone leaves or their login lapses. Access is granted folder by folder through collaborations, which makes the credential's reach explicit and auditable." }, |
| 125 | + { question: "The credential validates but every block returns nothing or 404s — why?", answer: "The Service Account's folder tree starts empty. It only sees folders it has been invited into as a collaborator. Invite its @boxdevedition.com email (shown on the app's General Settings tab) as an Editor on the folders your workflows use." }, |
| 126 | + { question: "Adding the credential fails and Box's token endpoint reports 'This app is not authorized by the enterprise admin' — what now?", answer: "Sim surfaces this as its general authentication error. A Box admin or co-admin must authorize the app in Admin Console → Apps → Platform Apps Manager (or Platform → Platform Apps in some tenants) by adding its Client ID. Until then, all token requests fail." }, |
| 127 | + { question: "I added a scope but tools still fail with 403 — why?", answer: "Authorization is a snapshot of the app's scopes at the time the admin approved it. After any scope or access-level change, the admin must re-authorize the app in Platform Apps Manager before the new scopes apply." }, |
| 128 | + { question: "Box rejects the token request with 'The grant type is unauthorized for this client_id' — why?", answer: "The app was created with user authentication (OAuth 2.0) instead of Server Authentication, and Sim reports it couldn't authenticate with those credentials. Create a new Platform App and choose Server Authentication (with Client Credentials Grant)." }, |
| 129 | + { question: "Box rejects the token request with 'Grant credentials are invalid' — why?", answer: "Either the Client ID, Client secret, and Enterprise ID don't all belong to the same Box app and enterprise (most often a mismatched ID/secret pair), or the app hasn't been authorized in the Admin Console yet. Re-copy all three values from the same app in the Developer Console, and make sure an admin has authorized the app in Platform Apps Manager." }, |
| 130 | + { question: "Do Box Sign operations work with a service account?", answer: "Yes, if the app has the Manage signature requests scope, the admin has (re-)authorized the app since it was added, and Box Sign is enabled on your enterprise plan. File and folder operations work regardless." }, |
| 131 | +]} /> |
0 commit comments