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

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

Next Steps

For production deployment, see clickup-prod-checklist.