Skip to content

Commit d617de7

Browse files
waleedlatif1waleedlatif1
committed
feat(credentials): docs pages for Zoom/Box/Salesforce service accounts + connect-label fix
Connect dropdown now consults client-credential descriptors too, so Zoom and Salesforce render their vendor nouns instead of the generic fallback. Sidebar section gains the four new pages
1 parent b819002 commit d617de7

5 files changed

Lines changed: 449 additions & 6 deletions

File tree

‎apps/docs/content/docs/en/integrations/box-service-account.mdx‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
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 (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 (Client Credentials Grant)**
25+
26+
{/* TODO(screenshot): Box Developer Console Create Platform App dialog with Server Authentication (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 shown on the app's **General Settings** tab, or 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** 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 your workspace **Settings** and go to the **Integrations** tab
91+
</Step>
92+
<Step>
93+
Search for "Box" and click 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, you'll see a specific error explaining what went wrong (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.
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 tab) as an Editor on the folders your workflows use." },
126+
{ question: "Adding the credential fails with 'This app is not authorized by the enterprise admin' — what now?", answer: "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: "It says '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. Create a new Platform App and choose Server Authentication (Client Credentials Grant)." },
129+
{ question: "It says 'Grant credentials are invalid' — why?", answer: "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. Re-copy all three values from the same app in the Developer Console." },
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+
]} />

‎apps/docs/content/docs/en/integrations/meta.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,17 +6,20 @@
66
"asana-service-account",
77
"atlassian-service-account",
88
"attio-service-account",
9+
"box-service-account",
910
"calcom-service-account",
1011
"google-service-account",
1112
"hubspot-service-account",
1213
"linear-service-account",
1314
"monday-service-account",
1415
"notion-service-account",
1516
"pipedrive-service-account",
17+
"salesforce-service-account",
1618
"shopify-service-account",
1719
"trello-service-account",
1820
"wealthbox-service-account",
1921
"webflow-service-account",
22+
"zoom-service-account",
2023
"---All Integrations---",
2124
"a2a",
2225
"agentmail",

0 commit comments

Comments
 (0)