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

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

Prerequisites

• Named credential owner, approved secret manager, and rotation/incident path
• Environment-specific identities and least-privilege workspace/list inventory
• Secret scanning, log-redaction, and callback security checks in CI/runtime

Instructions

Store credentials only through approved injection, restrict each identity to its environment and required resources, validate authorization before mutations, and test rotation/revocation in staging. Treat a leaked credential or unexpected scope as an incident: revoke/contain it, review access logs, and restore only a scoped replacement.

Output

Maintain a security record with identity/secret reference, effective scope, rotation test, scanning/redaction evidence, webhook controls, incident owner, and exceptions. Never place live tokens, raw task content, or private audit records in this documentation or its logs.

Examples

Rotate a staging service token, verify only its intended list is accessible, and confirm a revoked token produces a safe 401 without leaking headers. If a token appears in history or a client bundle, revoke it immediately and block release until secret scanning and deployment references are corrected.

Resources

• ClickUp Authentication
• ClickUp Common Errors

Next Steps

For production deployment, see clickup-prod-checklist.