ClickUp Security Basics
Overview
Secure ClickUp API credentials and access patterns. ClickUp personal tokens never expire, making rotation discipline critical. OAuth tokens also do not expire but can be revoked.
Token Types and Risk
| Token Type | Prefix | Expires | Scope | Risk Level |
|---|
| Personal API Token | pk_ | Never | Full user access | High -- treat like password |
| OAuth Access Token | Varies | Never | Per-authorized workspace | Medium -- per-user |
| OAuth Client Secret | N/A | Never | App-level | Critical -- server-side only |
Secure Storage
CLICKUP_API_TOKEN=pk_12345678_ABCDEFGHIJKLMNOPQRSTUVWXYZ
.env
.env.local
.env.*.local
*.pem
if git diff --cached --diff-filter=ACM | grep -qE "pk_[a-zA-Z0-9_]{30,}"; then
echo "ERROR: ClickUp API token detected in staged files!"
echo "Remove the token and use environment variables instead."
exit 1
fi
Token Rotation Procedure
export CLICKUP_API_TOKEN="pk_NEW_TOKEN_HERE"
curl -sf https://api.clickup.com/api/v2/user \
-H "Authorization: $CLICKUP_API_TOKEN" | jq '.user.username'
gh secret set CLICKUP_API_TOKEN --body "$CLICKUP_API_TOKEN"
Least Privilege with OAuth Scopes
When building OAuth apps, request only needed access. ClickUp OAuth grants workspace-level access per authorized workspace.
function getAuthUrl(workspaceId?: string): string {
const params = new URLSearchParams({
client_id: process.env.CLICKUP_CLIENT_ID!,
redirect_uri: process.env.CLICKUP_REDIRECT_URI!,
});
return `https://app.clickup.com/api?${params}`;
}
Environment-Specific Tokens
function getClickUpToken(): string {
const env = process.env.NODE_ENV ?? 'development';
const tokenKey = {
development: 'CLICKUP_API_TOKEN_DEV',
staging: 'CLICKUP_API_TOKEN_STAGING',
production: 'CLICKUP_API_TOKEN_PROD',
}[env] ?? 'CLICKUP_API_TOKEN';
const token = process.env[tokenKey];
if (!token) throw new Error(`Missing ${tokenKey} for environment: ${env}`);
return token;
}
Audit Logging
interface ClickUpAuditEntry {
timestamp: string;
method: string;
endpoint: string;
statusCode: number;
rateLimitRemaining: number;
userId?: string;
}
function logApiCall(entry: ClickUpAuditEntry): void {
console.log(JSON.stringify({
level: 'audit',
service: 'clickup',
...entry,
}));
}
async function auditedRequest(path: string, options: RequestInit = {}) {
const response = await fetch(`https://api.clickup.com/api/v2${path}`, {
...options,
headers: { 'Authorization': getClickUpToken(), ...options.headers },
});
logApiCall({
timestamp: new Date().(),
: options. ?? ,
: path,
: response.,
: (
response..() ??
),
});
response;
}
Security Checklist
Error Handling
| Issue | Detection | Mitigation |
|---|
| Token in git history | git log -p --all -S 'pk_' | Rotate token immediately; use BFG Repo-Cleaner |
| Token in client bundle | Build output grep | Move to server-side only |
| Stale token after rotation | 401 errors spike | Update all deployments |
Resources
Next Steps
For production deployment, see clickup-prod-checklist.
