ClickUp Security Basics Skill

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

# .env (NEVER commit)
CLICKUP_API_TOKEN=pk_12345678_ABCDEFGHIJKLMNOPQRSTUVWXYZ

# .gitignore (mandatory)
.env
.env.local
.env.*.local
*.pem

# Git pre-commit hook to catch leaked tokens
# .git/hooks/pre-commit
#!/bin/bash
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

# 1. Generate new token: ClickUp > Settings > Apps > Regenerate
# 2. Update environment
export CLICKUP_API_TOKEN="pk_NEW_TOKEN_HERE"

# 3. Verify new token works
curl -sf https://api.clickup.com/api/v2/user \
  -H "Authorization: $CLICKUP_API_TOKEN" | jq '.user.username'

# 4. Update secrets in deployment platform
gh secret set CLICKUP_API_TOKEN --body "$CLICKUP_API_TOKEN"
# or: vault kv put secret/clickup/api-token value="$CLICKUP_API_TOKEN"
# or: aws secretsmanager update-secret --secret-id clickup-api-token --secret-string "$CLICKUP_API_TOKEN"

# 5. Old token is automatically invalidated when you regenerate

Least Privilege with OAuth Scopes

When building OAuth apps, request only needed access. ClickUp OAuth grants workspace-level access per authorized workspace.

// OAuth: only request the workspaces you need
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 {
  // Structured log for SIEM/audit systems
  console.log(JSON.stringify({
    level: 'audit',
    service: 'clickup',
    ...entry,
  }));
}

// Wrap all API calls
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().toISOString(),
    method: options.method ?? 'GET',
    endpoint: path,
    statusCode: response.status,
    rateLimitRemaining: parseInt(
      response.headers.get('X-RateLimit-Remaining') ?? '-1'
    ),
  });

  return response;
}

Security Checklist

[ ] API tokens stored in environment variables, never in code
[ ] .env files listed in .gitignore
[ ] Pre-commit hook scanning for token patterns (pk_*)
[ ] Separate tokens for dev/staging/production
[ ] Token rotation procedure documented and tested
[ ] Audit logging on all API calls
[ ] OAuth client secret server-side only (never in frontend)
[ ] Webhook endpoints use HTTPS only

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.

Agent Skills: ClickUp Security Basics

Install this agent skill to your local

Skill Files