ElevenLabs Security Basics

Overview

Security best practices for ElevenLabs API key management, webhook HMAC signature verification, and protecting cloned voice data. ElevenLabs uses a single API key (xi-api-key) and HMAC webhook authentication.

This SKILL.md carries the workflow at a high level with the essential skeletons. Full production code for each step lives in references/implementation.md, and end-to-end scenarios live in references/examples.md.

Prerequisites

• ElevenLabs SDK installed
• Understanding of environment variables
• Access to ElevenLabs dashboard (Settings > API Keys)

Instructions

Step 1: API Key Management

Keep keys out of source, and add a hook that blocks accidental commits:

bash
# .env (NEVER commit to git)
ELEVENLABS_API_KEY=sk_your_key_here

# .gitignore — MUST include these
.env
.env.local
.env.*.local

bash
#!/bin/bash
# .git/hooks/pre-commit — reject staged ElevenLabs keys
if git diff --cached | grep -qE 'sk_[a-zA-Z0-9]{20,}'; then
  echo "ERROR: ElevenLabs API key detected in staged changes!"
  echo "Remove the key and use environment variables instead."
  exit 1
fi

Step 2: Environment-Specific Keys

Load the key at startup, fail fast when it is missing, and warn if a production key leaks into development. Full getSecurityConfig() implementation: references/implementation.md.

Step 3: Webhook HMAC Signature Verification

ElevenLabs webhooks carry an ElevenLabs-Signature header formatted as t=TIMESTAMP,v1=SIGNATURE. Verify it with HMAC-SHA256, reject timestamps older than 5 minutes (replay protection), and use a timing-safe comparison. Full verifyWebhookSignature() implementation: references/implementation.md.

Step 4: Express Webhook Endpoint with Verification

Verify against the raw request body, respond 200 fast, then process asynchronously so you never trip the webhook timeout. Full endpoint: references/implementation.md.

Step 5: API Key Rotation Procedure

Generate the new key, validate it before cutover, push to every environment, verify production, then revoke the old key — zero downtime. Full runbook: references/implementation.md.

Step 6: Voice Data Protection

Cloned voices are biometric PII: restrict who can clone, audit-log every operation, and require documented consent. Full policy and audit logger: references/implementation.md.

Output

Applying this skill produces a hardened ElevenLabs integration:

• API keys stored only in environment variables, with .env gitignored and a

pre-commit hook that blocks the sk_ key pattern.

• A verifyWebhookSignature() helper and Express endpoint that reject invalid

signatures (HTTP 401) and replayed requests (timestamp > 5 minutes).

• A documented, zero-downtime key rotation runbook.
• Structured audit logs (elevenlabs.voice.audit) for every voice clone,

delete, and use, plus a completed Security Checklist below.

Security Checklist

• ] API keys in environment variables (never in source code)
• ] .env files in .gitignore
• ] Different API keys for dev/staging/prod
• ] Pre-commit hook scanning for key patterns (sk_)
• ] Webhook signatures verified with HMAC-SHA256
• ] Replay protection on webhooks (5-minute timestamp check)
• ] Webhook failures monitored (auto-disabled after 10 consecutive failures)
• ] Voice cloning operations audit-logged
• ] Cloned voice consent documented
• ] API key rotation scheduled quarterly

Webhook Failure Policy

ElevenLabs auto-disables webhooks after:

• 10+ consecutive delivery failures, AND
• Last successful delivery was 7+ days ago (or never delivered)

Always return HTTP 200 quickly from your webhook handler.

Error Handling

| Security Issue | Detection | Mitigation | |----------------|-----------|------------| | Exposed API key | Git scanning, CI check | Rotate immediately, revoke old key | | Invalid webhook signature | verifyWebhookSignature() returns false | Log and reject (HTTP 401) | | Replay attack | Timestamp > 5 minutes old | Reject with timestamp check | | Unauthorized voice cloning | Audit logs | Restrict clone permissions |

Examples

Worked, end-to-end scenarios live in references/examples.md:

• Block a key commit before it happens — the pre-commit hook aborts a

commit containing sk_....

• Reject a replayed webhook — a correct HMAC still fails on a 6-minute-old

timestamp.

• Rotate a leaked production key with zero downtime — validate the new key,

cut over, then revoke.

• Audit a voice-clone operation — structured JSON proving who cloned a

voice and whether consent was on file.

Resources

• ElevenLabs Webhooks
• ElevenLabs API Keys
• Voice Cloning Policy

Next Steps

Once these basics are in place, harden the wider deployment: apply the elevenlabs-prod-checklist skill for production readiness, schedule the quarterly key rotation from Step 5, and wire the voice audit logs into your central logging or SIEM so cloning activity is reviewable.