Skip to content

Commit 00a2f26

Browse files
waleedlatif1waleedlatif1
authored
feat(credentials): token-paste service accounts for 12 providers (#5682)
* feat(credentials): token-paste service accounts for 12 providers (HubSpot, Airtable, Notion, Asana, Attio, Linear, monday, Shopify, Webflow, Trello, Cal.com, Wealthbox) * refactor(credentials): registry-dispatch service accounts + doc-verified validator hardening - Migrate Google/Atlassian/Slack service-account branches to the same registry pattern as token-paste providers (builder + resolver maps, unified required-fields contract validation) - Fix Shopify service-account store domain never reaching tool URL builders - Linear: rate-limit 400s no longer mislabeled as invalid credentials; validation header matches runtime header rule - Trello: server API key rejection no longer blamed on customer token - Fleet-wide: network errors and non-JSON provider bodies map to provider_unavailable via shared fetchProvider/parseProviderJson - HubSpot: drop regional-host displayName upgrade; Wealthbox: explicit 402; monday: provider-side GraphQL errors mapped correctly; Attio: null-body guard * polish(credentials): ship-gate fixes, setup-guide docs, and lint pass for token service accounts - 12 setup-guide docs pages (docs.sim.ai/integrations/<provider>-service-account) incl. the Trello authorize-link flow the integration depends on - Attio: HTTP 400 on /v2/self maps to invalid_credentials (live-verified) - monday: scan all GraphQL errors for provider-side codes; no empty audit ids - Compile-time descriptor/validator lockstep (typed registry) and prototype-safe provider-id guard (Object.hasOwn) - Shared errors.test.ts pinning fetchProvider/parseProviderJson/ throwForProviderResponse guarantees for all validators - Stale TSDoc updated after the registry migration; biome organizeImports pass * docs(credentials): vendor-doc accuracy pass on service-account setup guides 34 corrections from a 12-agent audit against live official vendor docs: current HubSpot Development-area nav, Notion connections rename, monday Developer Center paths, Shopify legacy-vs-Dev-Dashboard token flows, and hedged wording for claims vendors do not document (expiry, limits) * improvement(credentials): vendor-accurate credential nouns on connect surfaces 'Add service account' only where the vendor actually has service accounts (Google, Atlassian); token-paste providers now use their own vocabulary via a connectNoun descriptor field — 'Add private app token' (HubSpot), 'Add API key' (Attio/Linear/Cal.com), 'Add personal access token' (Airtable), etc. Docs page titles updated to match; slugs and internal provider ids unchanged * fix(credentials): classify auth-shaped Shopify GraphQL errors as invalid credentials Shopify can reject invalid or revoked shpat_ tokens with HTTP 200 and a GraphQL error body instead of a 401; those now map to invalid_credentials instead of a provider-outage message * fix(credentials): empirically-grounded HubSpot token verification Live probing showed the documented access-token-info route returns a bare 404 for unrecognized tokens (ambiguous with a missing route), so 404/400 now falls back to the Account Information API, which answers with a JSON 401 for rejected tokens and 200/403 for live ones — verified against the real endpoints * fix(credentials): review-round-2 fixes for service-account edge cases - Shopify tools prefer the credential-validated store domain over the block's auto-detected shopDomain (a store-bound token must hit its own store) - Unknown non-empty service-account providerIds are rejected instead of silently persisting as google-service-account (empty stays the legacy Google fallback) - Shopify/modal domain normalization strips URL paths ('https://x.myshopify.com/admin') - monday: warning-class GraphQL errors no longer reject a token whose me data proves it authenticated * chore(credentials): format shopify validator test * fix(credentials): cold-review hardening pass - Object.hasOwn guards on all provider-id registry lookups (crafted '__proto__'/'constructor' providerIds now 400 instead of 500) + regression test - fetchProvider gets a 10s AbortSignal.timeout so a hung provider can't pin the create/reconnect request - HubSpot: unexpected 403 on the token-info route defers to the account-info fallback instead of blaming the token - Linear selector routes use the SDK apiKey option for lin_api_ keys (bare header parity with the tools sweep) - Docs: UI steps aligned to the vendor-noun connect labels; HubSpot scope-propagation claims softened; Trello in-product-link promise corrected
1 parent 9254984 commit 00a2f26

157 files changed

Lines changed: 5486 additions & 238 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

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

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
---
2+
title: Airtable Personal Access Tokens
3+
description: Set up an Airtable personal access token with scoped base access to use Airtable in Sim workflows
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+
Airtable personal access tokens (PATs) let your workflows authenticate to Airtable with a token that has explicit scopes and explicit base access — instead of a person's OAuth login. The token never expires on its own, and what it can touch is decided at creation time.
11+
12+
On Airtable Enterprise Scale plans, admins can create the same tokens from a dedicated **service account** in the Admin Panel. Those tokens are wire-identical to personal access tokens and are the better choice for organization-level use: they don't stop working when an employee leaves.
13+
14+
## Prerequisites
15+
16+
Any Airtable user can create a personal access token for the bases they have access to. Keep in mind the token is capped by its creator's own permissions — a PAT created by a read-only collaborator cannot write, no matter which scopes it has. Create the token from an account with the access level your workflows need.
17+
18+
For service-account tokens, you need an Enterprise Scale plan and an admin with access to the Admin Panel.
19+
20+
## Creating the Token
21+
22+
<Steps>
23+
<Step>
24+
Open [airtable.com/create/tokens](https://airtable.com/create/tokens) and click **Create token**
25+
26+
{/* TODO(screenshot): Airtable token builder page with the "Create token" button */}
27+
</Step>
28+
<Step>
29+
Give the token a name (e.g. `sim-airtable-bot`)
30+
</Step>
31+
<Step>
32+
Add the scopes your workflows need. The full set Sim's Airtable tools and triggers use is:
33+
34+
```
35+
data.records:read
36+
data.records:write
37+
schema.bases:read
38+
user.email:read
39+
webhook:manage
40+
```
41+
42+
Reading records needs `data.records:read`; creating, updating, upserting, and deleting records need `data.records:write`; listing bases and tables and reading base schemas need `schema.bases:read`; `user.email:read` lets Sim show the token owner's email as the credential name; and `webhook:manage` is only needed if you use Airtable triggers in Sim.
43+
44+
{/* TODO(screenshot): token builder scopes section with the five scopes added */}
45+
</Step>
46+
<Step>
47+
Under **Access**, add the bases or entire workspaces the token should reach. The token can only see what you list here — a token with all five scopes but no base access can't read anything.
48+
49+
{/* TODO(screenshot): token builder access section with a workspace added */}
50+
</Step>
51+
<Step>
52+
Click **Create token** and copy it when it's shown. Airtable only displays it once — if you close the dialog, you'll have to regenerate it.
53+
</Step>
54+
</Steps>
55+
56+
<Callout type="warn">
57+
The token is bearer credentials for every base you granted. Treat it like a password — do not commit it to source control or share it publicly. Sim encrypts the token at rest.
58+
</Callout>
59+
60+
### Enterprise Scale: Service Account Tokens
61+
62+
On Enterprise Scale plans, an admin can create up to 30 service accounts (raisable via Airtable support) from the Admin Panel, each with its own name and email. From a service account's **Personal access tokens** panel, the admin creates tokens with the same scopes-plus-base-access builder shown above. The resulting token works in Sim exactly like a user PAT — same format, same `pat…` prefix, same behavior — but it belongs to the organization, not a person, so it survives employee offboarding. If your plan supports it, prefer this over a user-created PAT.
63+
64+
<Callout type="info">
65+
Enterprise organizations can enable "Block API access to organization-owned bases and workspaces". If your organization uses this setting, the service account must be allowlisted or every call fails despite a valid token.
66+
</Callout>
67+
68+
## Adding the Service Account to Sim
69+
70+
<Steps>
71+
<Step>
72+
Open your workspace **Settings** and go to the **Integrations** tab
73+
</Step>
74+
<Step>
75+
Search for "Airtable Service Account" and click it, then click **Add to Sim** and choose **Add personal access token**
76+
77+
{/* TODO(screenshot): Integrations page with "Airtable Service Account" in the service list */}
78+
</Step>
79+
<Step>
80+
Paste the **Personal access token**, and optionally set a display name and description
81+
82+
{/* TODO(screenshot): Add Airtable personal access token dialog with the personal access token filled in */}
83+
</Step>
84+
<Step>
85+
Click **Add personal access token**. Sim verifies the token by calling Airtable's `whoami` endpoint — if it fails, you'll see a specific error explaining what went wrong.
86+
</Step>
87+
</Steps>
88+
89+
<Callout type="warn">
90+
Validation only proves the token is real — Airtable doesn't expose a PAT's scopes or base access for inspection. A token that validates fine can still fail every tool call if you skipped a scope or forgot to grant base access. If a block returns a 403 (`INVALID_PERMISSIONS`) or an unexpected 404 (`NOT_FOUND`), check the token's scopes and base access first.
91+
</Callout>
92+
93+
## Using the Service Account in Workflows
94+
95+
Add an Airtable block to your workflow. In the credential dropdown, your Airtable service account appears alongside any OAuth credentials. Select it and configure the block as you normally would.
96+
97+
{/* TODO(screenshot): Airtable block in a workflow with the Airtable service account selected as the credential */}
98+
99+
The block calls `api.airtable.com` using the token — exactly the same requests as the OAuth flow, so every Airtable tool works unchanged, limited to the scopes and bases you granted.
100+
101+
<FAQ items={[
102+
{ question: "Why a personal access token instead of OAuth?", answer: "PATs don't expire and don't depend on any user staying logged in or re-consenting. You decide scopes and base access once at creation, and the token is stable until you regenerate or delete it — which is what you want for an automated workflow." },
103+
{ question: "What's the difference between a user PAT and a service-account PAT?", answer: "Nothing on the wire — both are the same token format and behave identically in Sim. The difference is ownership: a user PAT dies with the user's base access (or when they leave the org), while a service-account PAT (Enterprise Scale, created in the Admin Panel) belongs to the organization." },
104+
{ question: "My token validates but every block fails with 403 or 404 — why?", answer: "The token is missing a scope or, more commonly, base access. Airtable deliberately blurs the two: an unauthorized base can return 403 INVALID_PERMISSIONS or a plain 404 NOT_FOUND. Edit the token at airtable.com/create/tokens and check both the scopes list and the Access section." },
105+
{ question: "Do tokens expire?", answer: "No. Airtable PATs remain active indefinitely until they're manually deleted, regenerated, or modified. A user PAT also stops working if its creator loses access to the granted bases or leaves the organization." },
106+
{ question: "How do I rotate the token?", answer: "Create a new token with the same scopes and base access, update the credential in Sim with the new token, and once it's working, delete the old one. Note that regenerating an existing token invalidates the old value immediately." },
107+
{ question: "Do I need the webhook:manage scope?", answer: "Only if you use Airtable triggers in Sim — the trigger creates and manages webhooks on your base. For workflows that only read and write records, you can omit it." },
108+
]} />

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

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
---
2+
title: Asana Service Accounts & Personal Access Tokens
3+
description: Connect Asana to Sim with a service account token or a personal access token from a dedicated bot account
4+
---
5+
6+
import { Callout } from 'fumadocs-ui/components/callout'
7+
import { Step, Steps } from 'fumadocs-ui/components/steps'
8+
import { Image } from '@/components/ui/image'
9+
import { FAQ } from '@/components/ui/faq'
10+
11+
Asana service accounts let your workflows authenticate as a non-human bot identity instead of a person's account. The service account has its own name and its own token, managed centrally by a super admin — no one person's OAuth consent to expire, and access can be revoked without touching anyone's personal account.
12+
13+
There are two ways to get a token, and both work in Sim:
14+
15+
- **Service account token** (recommended for teams) — available on Asana **Enterprise** and **Enterprise+** plans, created by a super admin in the Admin Console.
16+
- **Personal access token (PAT)** — available on any plan, created from any user account. For production workflows, create it from a dedicated bot account rather than a personal one.
17+
18+
Both token types use the same format and paste into the same field in Sim.
19+
20+
## Option A: Service Account Token (Enterprise / Enterprise+)
21+
22+
### Prerequisites
23+
24+
You need an Asana **super admin** on an **Enterprise** or **Enterprise+** plan. Service accounts are an organization-level feature — regular users cannot create them.
25+
26+
### Create the Service Account
27+
28+
<Steps>
29+
<Step>
30+
Open the Asana **Admin Console** and go to **Apps** → **Service accounts**
31+
32+
{/* TODO(screenshot): Asana Admin Console with Apps → Service accounts highlighted */}
33+
</Step>
34+
<Step>
35+
Click **Add service account**, give it a name (e.g. `Sim Integration`) — this is the name that will appear on tasks and comments the workflows create
36+
</Step>
37+
<Step>
38+
Grant the service account **Full Permissions**. Scoped service accounts (for example, ones limited to User Provisioning / SCIM) cannot call the standard Asana API and will fail when you connect them to Sim
39+
40+
{/* TODO(screenshot): service account permission picker with "Full Permissions" selected */}
41+
</Step>
42+
<Step>
43+
Copy the token when it's shown. Asana only displays it once — if you lose it, you'll have to regenerate it — plan to update the credential in Sim at the same time, since the old token stops working once it's replaced.
44+
</Step>
45+
</Steps>
46+
47+
<Callout type="warn">
48+
A service account with Full Permissions has org-wide access to all data in your Asana organization, including private projects. Treat the token like an admin password.
49+
</Callout>
50+
51+
## Option B: Personal Access Token
52+
53+
If you're not on an Enterprise plan, a personal access token works identically on the wire. For production workflows, create a dedicated bot user account (e.g. `sim-bot@yourcompany.com`) and generate the PAT from that account — a PAT is tied to the user who created it, inherits only that user's permissions, and stops working if the user is deprovisioned.
54+
55+
<Steps>
56+
<Step>
57+
Log in as the bot account and open the developer console at [app.asana.com/0/my-apps](https://app.asana.com/0/my-apps)
58+
59+
{/* TODO(screenshot): Asana developer console "My apps" page with "Create new token" button */}
60+
</Step>
61+
<Step>
62+
Click **+ Create new token**, give it a name that describes its use (e.g. `Sim Integration`), and click **Create token**
63+
</Step>
64+
<Step>
65+
Copy the token immediately — Asana only shows it once.
66+
</Step>
67+
<Step>
68+
Add the bot account to the workspaces and projects your workflows need. A PAT can only see what its user can see.
69+
</Step>
70+
</Steps>
71+
72+
## Adding the Token to Sim
73+
74+
<Steps>
75+
<Step>
76+
Open your workspace **Settings** and go to the **Integrations** tab
77+
</Step>
78+
<Step>
79+
Search for "Asana Service Account" and click it, then click **Add to Sim** and choose **Add access token**
80+
81+
{/* TODO(screenshot): Integrations page with "Asana Service Account" in the service list */}
82+
</Step>
83+
<Step>
84+
Paste the token — service account token or personal access token, both work in the same field — and optionally set a display name and description
85+
86+
{/* TODO(screenshot): Add Asana access token dialog with the access token filled in */}
87+
</Step>
88+
<Step>
89+
Click **Add access token**. Sim verifies the token by calling Asana's `/users/me` endpoint — if it fails, you'll see a specific error explaining what went wrong.
90+
</Step>
91+
</Steps>
92+
93+
<Callout type="info">
94+
If a brand-new token fails validation with an authentication error, wait a few minutes and try again — newly created service account tokens can take a short time to become active.
95+
</Callout>
96+
97+
The token is encrypted before being stored.
98+
99+
## Using the Service Account in Workflows
100+
101+
Add an Asana block to your workflow. In the credential dropdown, your Asana service account appears alongside any OAuth credentials. Select it and configure the block as you normally would.
102+
103+
{/* TODO(screenshot): Asana block in a workflow with the service account selected as the credential */}
104+
105+
The block calls the Asana API (`app.asana.com/api/1.0`) with the token as a standard Bearer credential. There's no impersonation step — the token acts as itself: the service account identity, or the bot user for a PAT.
106+
107+
<FAQ items={[
108+
{ question: "What's the difference between a service account token and a personal access token?", answer: "A service account is an org-level bot identity with its own name and (with Full Permissions) org-wide access — it isn't tied to any person. A PAT is tied to the user who created it, inherits only their permissions, and breaks if that user is deactivated. Both use the same token format and paste into the same field in Sim; prefer the service account for team use if your plan supports it." },
109+
{ question: "Why does my scoped service account fail to connect?", answer: "Scoped service accounts (e.g. limited to User Provisioning / SCIM) can't call the standard Asana API, so Sim's validation call fails. Ask your super admin to create the service account with Full Permissions." },
110+
{ question: "Does the token expire?", answer: "No scheduled expiry — the token is long-lived until a super admin revokes or regenerates it (for a PAT, until the user deletes it or is deprovisioned). If a working credential suddenly starts failing with 401 errors, the token was revoked; paste a new one." },
111+
{ question: "How do I rotate the token?", answer: "Regenerate the service account token in the Admin Console, then update the credential in Sim with the new token right away — the old token stops working once it's replaced, so expect a brief window of failed runs if workflows execute in between." },
112+
{ question: "Do I need to enter a workspace or domain?", answer: "No. Asana has a single API host, and Sim's Asana blocks take workspace and project IDs as block parameters — the token is all the credential needs." },
113+
{ question: "Will one shared token hit rate limits?", answer: "Asana rate-limits per token, so all workflows sharing one service account token draw from a single rate-limit bucket. If you run heavy concurrent workloads, watch for 429 responses and consider splitting workloads across tokens." },
114+
]} />

0 commit comments

Comments
 (0)