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:
ELEVENLABS_API_KEY=sk_your_key_here
.env
.env.local
.env.*.local
#!/bin/bash
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
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
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.
