Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/clay-security-basics/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill clay-security-basics. Copyright stays with the author (MIT).

Clay Security Basics

Overview

Security best practices for Clay integrations covering API key management, webhook endpoint security, provider credential isolation, and lead data protection. Clay handles sensitive PII (emails, phone numbers, LinkedIn profiles) at scale, making security critical.

Prerequisites

• Clay account with admin access
• Understanding of environment variables and secrets management
• Access to deployment platform's secrets manager

Instructions

Step 1: Secure API Key Storage

# .env (NEVER commit to git)
CLAY_API_KEY=clay_ent_your_api_key_here
CLAY_WEBHOOK_URL=https://app.clay.com/api/v1/webhooks/your-id

# .gitignore — add these patterns
.env
.env.local
.env.*.local
*.key

For production, use your platform's secrets manager:

# GitHub Actions
gh secret set CLAY_API_KEY --body "clay_ent_your_key"

# Google Cloud Secret Manager
echo -n "clay_ent_your_key" | gcloud secrets create clay-api-key --data-file=-

# AWS Secrets Manager
aws secretsmanager create-secret \
  --name clay/api-key \
  --secret-string "clay_ent_your_key"

Step 2: Authenticate Incoming Webhook Callbacks

When Clay's HTTP API columns call your endpoint, validate the request origin:

// src/middleware/clay-auth.ts
import crypto from 'crypto';

const CLAY_WEBHOOK_SECRET = process.env.CLAY_WEBHOOK_SECRET!;

function verifyClayCallback(
  payload: string,
  signature: string | undefined
): boolean {
  if (!signature || !CLAY_WEBHOOK_SECRET) return false;

  const expected = crypto
    .createHmac('sha256', CLAY_WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

// Express middleware
function clayAuthMiddleware(req: any, res: any, next: any) {
  const signature = req.headers['x-clay-signature'] as string;
  const rawBody = JSON.stringify(req.body);

  if (!verifyClayCallback(rawBody, signature)) {
    console.warn('Rejected unauthorized Clay callback from', req.ip);
    return res.status(401).json({ error: 'Invalid signature' });
  }
  next();
}

Step 3: Isolate Provider API Keys

Connect provider keys directly in Clay (Settings > Connections) rather than passing them through your application. This keeps provider credentials out of your codebase:

Step 4: API Key Rotation Procedure

# 1. Generate new key in Clay Settings > API
# 2. Update all integrations with new key
# 3. Test connectivity
curl -s -X POST "https://api.clay.com/v1/people/enrich" \
  -H "Authorization: Bearer $NEW_CLAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}' | jq .status

# 4. Once confirmed working, revoke old key in Clay dashboard
# 5. Update deployment secrets
gh secret set CLAY_API_KEY --body "$NEW_CLAY_API_KEY"

Step 5: Protect Enriched Lead Data

// src/clay/data-protection.ts
const PII_FIELDS = ['email', 'phone', 'personal_email', 'home_address', 'linkedin_url'];

/** Strip PII from enriched data before logging or analytics */
function redactPII(row: Record<string, unknown>): Record<string, unknown> {
  const redacted = { ...row };
  for (const field of PII_FIELDS) {
    if (field in redacted) {
      redacted[field] = '[REDACTED]';
    }
  }
  return redacted;
}

/** Hash email for deduplication without storing plaintext */
function hashEmail(email: string): string {
  return crypto.createHash('sha256').update(email.toLowerCase().trim()).digest('hex');
}

// Usage: log enriched data safely
console.log('Enriched:', redactPII(enrichedRow));

Step 6: Security Checklist

• API keys stored in environment variables or secrets manager
• .env files in .gitignore
• Webhook callback endpoints validate request signatures
• Provider API keys connected in Clay UI (not in application code)
• API key rotation procedure documented and tested
• Enriched PII data redacted in application logs
• Clay workspace uses separate API keys per integration
• Least privilege: viewers can't run enrichments or export data
• No hardcoded Clay URLs or keys in source code
• git-secrets or similar scanning enabled in CI

Error Handling

Output

Maintain a security-control record with secret references and owners, effective roles, callback authentication result, PII logging/redaction evidence, rotation date, incident route, and approved exceptions. Never include live tokens, webhook secrets, raw enrichment records, or audit-export contents in this record or its supporting logs.

Examples

Rotate a staging key through the secret manager, confirm the service restarts with the new reference, and prove that a callback with an invalid signature is rejected without logging its body. If a key or PII appears in history/logs, revoke or contain it, follow the incident process, and verify the corrective control before re-enabling the integration.

Resources

• Clay Plans & Billing
• OWASP API Security Top 10

Next Steps

For production deployment, see clay-prod-checklist.