Skip to content

Commit ca53128

Browse files
waleedlatif1waleedlatif1
committed
fix(docs): restore clickup-service-account guide and shield it from doc generation
The generator prunes integration pages it does not derive from blocks; add the hand-written ClickUp API-token guide to HANDWRITTEN_INTEGRATION_DOCS so regeneration cannot delete it.
1 parent 99fb4f0 commit ca53128

2 files changed

Lines changed: 82 additions & 0 deletions

File tree

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

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
title: ClickUp API Tokens
3+
description: Connect ClickUp to Sim with a personal API token — ideally created from a dedicated service user for production workflows
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+
ClickUp personal API tokens let your workflows authenticate without an OAuth consent flow. A token gives full parity with the ClickUp API — everything Sim's ClickUp blocks can do over OAuth works with a token.
12+
13+
Tokens are bound to the user who creates them: every action a workflow takes is attributed to that user, and the token stops working if the user is deactivated or removed from the workspace. For production workflows, create the token from a dedicated service user (e.g. `sim-bot@yourcompany.com`) rather than a personal account.
14+
15+
## Prerequisites
16+
17+
A ClickUp account with access to the workspaces your workflows need. Any user can generate a personal API token from their settings.
18+
19+
## Creating the API Token
20+
21+
<Steps>
22+
<Step>
23+
Log in as the service user, click your avatar in ClickUp, and open **Settings**
24+
25+
{/* TODO(screenshot): ClickUp avatar menu with Settings highlighted */}
26+
</Step>
27+
<Step>
28+
In the sidebar, go to **Apps** (labeled **API Token** in some plans)
29+
</Step>
30+
<Step>
31+
Click **Generate** to create your personal token
32+
33+
{/* TODO(screenshot): ClickUp Apps page with the Generate API token button visible */}
34+
</Step>
35+
<Step>
36+
Copy the token — it starts with `pk_` — and store it somewhere safe.
37+
</Step>
38+
</Steps>
39+
40+
<Callout type="warn">
41+
The API token carries the creating user's full access to every workspace they belong to. Treat it like a password — do not commit it to source control or share it publicly. Sim encrypts the token at rest.
42+
</Callout>
43+
44+
## Adding the API Token to Sim
45+
46+
<Steps>
47+
<Step>
48+
Open your workspace **Settings** and go to the **Integrations** tab
49+
</Step>
50+
<Step>
51+
Search for "ClickUp Service Account" and click it, then click **Add to Sim** and choose **Add API token**
52+
53+
{/* TODO(screenshot): Integrations page with "ClickUp Service Account" in the service list */}
54+
</Step>
55+
<Step>
56+
Paste the API token (`pk_...`) and optionally set a display name and description
57+
58+
{/* TODO(screenshot): Add ClickUp API token dialog with the token filled in */}
59+
</Step>
60+
<Step>
61+
Click **Add API token**. Sim verifies the token by fetching the authorized user from ClickUp — if it fails, you'll see a specific error explaining what went wrong.
62+
</Step>
63+
</Steps>
64+
65+
The token is encrypted before being stored.
66+
67+
## Using the Service Account in Workflows
68+
69+
Add a ClickUp block to your workflow. In the credential dropdown, your ClickUp service account appears alongside any OAuth credentials. Select it and configure the block as you normally would.
70+
71+
{/* TODO(screenshot): ClickUp block in a workflow with the service account selected as the credential */}
72+
73+
The block calls the ClickUp API (`api.clickup.com`) with the token. Everything the workflow does — creating tasks, adding comments, uploading attachments — is attributed to the user who created the token.
74+
75+
<FAQ items={[
76+
{ question: "Does ClickUp have real service accounts?", answer: "Not for API tokens — every token is tied to a user. The closest equivalent is creating a dedicated service user in your workspace and generating the token from that account, so workflows aren't attributed to (or broken by) a real person's account." },
77+
{ question: "Does the token expire?", answer: "No — personal API tokens are long-lived and don't auto-rotate. They stay valid until regenerated, or until the user who created them is deactivated or removed from the workspace." },
78+
{ question: "What happens if the token's user leaves the company?", answer: "Tokens are user-bound, so deactivating the user kills the token and every workflow using it starts failing with authentication errors. This is exactly why production tokens should come from a dedicated service user." },
79+
{ question: "Which workspaces can the token reach?", answer: "Every workspace the creating user belongs to. Use the Get Workspaces operation to see what the token can access, and remember that removing the user from a workspace also removes the token's access to it." },
80+
{ question: "How do I rotate the token?", answer: "Regenerate the token from the same service user in ClickUp (regenerating invalidates the old one immediately), then update the credential in Sim with the new token." },
81+
]} />

‎scripts/generate-docs.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ const HANDWRITTEN_INTEGRATION_DOCS = new Set([
4040
'a2a',
4141
'google-service-account',
4242
'atlassian-service-account',
43+
'clickup-service-account',
4344
'hubspot-setup',
4445
])
4546

0 commit comments

Comments
 (0)