Skip to content
Twilio Security Hardening

Twilio Security Hardening Skill

Harden a Twilio integration against credential leaks and fraud — API keys instead of auth tokens, webhook signature validation, geo-permissions, SMS pumping prevention and zero-downtime credential rotation.

GitHub Docs

Install

Install with the skills CLI

One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from twilio/ai.

$ npx skills add twilio/ai --skill twilio-security-hardening

Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.

Other ways to install

  1. Open the skill on GitHub and download the folder that holds its SKILL.md.
  2. Put it at ~/.claude/skills/twilio-security-hardening/, where Claude Code picks it up in every project.

No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/twilio-security-hardening/SKILL.md works too.

Using another agent? Its personal skills folder
Codex
~/.agents/skills/
Cursor
~/.cursor/skills/
GitHub Copilot
~/.copilot/skills/
Gemini CLI
~/.gemini/skills/
Windsurf
~/.codeium/windsurf/skills/
OpenCode
~/.config/opencode/skills/

About

  • Auth token vs API key vs access token comparison with production guidance
  • Webhook signature verification and request validation patterns
  • SMS pumping prevention, geo-permissions and account isolation
  • Zero-downtime credential rotation procedure

Security on a telephony account is not a one-time setup step, because the failure modes cost real money: a leaked credential is an attacker sending your messages, and an unvalidated webhook is anyone able to drive your application. This skill covers the account-level decisions and the application-level patterns that prevent both.

The credential section is the one worth reading first. It lays out auth tokens (full account access, revocable only by rotating), API key and secret pairs (scoped and individually revocable — the right default for production, CI/CD and server-side code), and short-lived access tokens for client-side Voice, Video and Conversations SDKs. It flags a specific trap: rotating your auth token invalidates every integration authenticating with AccountSID:AuthToken and breaks webhook signature validation, while leaving SK-prefixed API keys untouched. Start with API keys and you rarely have to touch the auth token at all.

From there it covers request validation and webhook signature verification, account-level compliance posture for PCI DSS and HIPAA, fraud prevention including SMS pumping and geo-permissions, account isolation patterns, a list of common mistakes, and a zero-downtime credential rotation procedure.

Part of Twilio's official Skills set, MIT-licensed in the twilio/ai repository. Twilio Skills are a Public Beta product and not covered by Twilio's support terms or SLA.

SKILL.md

The instructions your agent loads, as published by Twilio.

SKILL.md
name
twilio-security-hardening
description
Secure Twilio applications against common attacks. Covers credential management (API keys vs auth tokens), request validation (webhook signature verification), PCI DSS compliance, HIPAA account requirements, SMS pumping prevention, geo-permissions, and account isolation patterns. Use this skill when developers are building or deploying Twilio apps.
Overview

Security hardening is an ongoing concern — not a one-time setup. This skill covers account-level security decisions and application-level protection patterns that prevent credential leaks, fraud, and compliance violations.

Lifecycle: Choose numbers (twilio-numbers-senders) → Register (twilio-compliance-onboarding) → Follow traffic rules (twilio-compliance-traffic) → Secure everything (this skill)

---

Credential Management
API Keys vs Auth Tokens
CredentialScopeRevocableUse when
Auth TokenFull account accessOnly by rotating (invalidates all token-based integrations and webhook signature validation — API keys unaffected)Avoid in production — use API keys instead
API Key + SecretScoped, revocable individuallyYes — revoke one without affecting othersProduction applications, CI/CD, server-side code
Access TokensShort-lived, client-specificExpire automaticallyClient-side SDKs (Voice, Video, Conversations)

Critical gotcha: Rotating your Auth Token invalidates all integrations authenticating with AccountSID:AuthToken and breaks webhook signature validation — it does NOT affect API keys (SK-prefixed), which are independent. Use API keys from the start so you rarely need to rotate the Auth Token.

Best Practices
  • Store credentials in environment variables or a secrets manager — never in code
  • Use different API keys per application/environment
  • Rotate API keys on a schedule (quarterly minimum, monthly for HIPAA)
  • Use sub-accounts to isolate customer credentials for ISV platforms — see twilio-account-setup

Docs: See twilio-iam-auth-setup for full credential setup patterns.

---

Request Validation (Webhook Security)

Verify that webhook requests actually come from Twilio — not spoofed by attackers.

X-Twilio-Signature Validation

Always use the SDK validator — don't implement HMAC-SHA1 manually:

Node.js

const twilio = require("twilio");

app.post("/sms", (req, res) => {
    const valid = twilio.validateRequest(
        process.env.TWILIO_AUTH_TOKEN,
        req.headers["x-twilio-signature"],
        `https://yourdomain.com/sms`,
        req.body
    );
    if (!valid) return res.status(403).send("Forbidden");
    // Process webhook...
});

Note: Webhook signature validation always uses your Auth Token — not an API Key Secret. This is the one legitimate production use of the Auth Token. Keep it accessible for request validation but store it securely (environment variable or secrets manager).

Common mistakes:

  • Using HTTP URL when Twilio sends to HTTPS (URL must match exactly)
  • Forgetting to include query string parameters in validation URL
  • Not validating in production because "it worked in dev without it"

Docs: See twilio-webhook-architecture for full webhook security patterns.

---

Account-Level Compliance
PCI DSS (Payment Card Industry)

PCI Mode is IRREVERSIBLE and account-wide. Once enabled, it cannot be disabled — ever.

  • All recordings are encrypted
  • Transcript access is restricted
  • Affects every service on the account

Recommendation: If you need PCI compliance for one use case, create a separate sub-account dedicated to payment-related calls. See twilio-account-setup for sub-account patterns.

For call recording during payment, pause recording when the customer gives card numbers:

client.calls(call_sid).recordings(recording_sid).update(status="paused")

Or use the <Pay> verb to handle payments without your application touching card data:

<Pay paymentConnector="stripe_connector" chargeAmount="49.99" currency="usd" />
HIPAA (Healthcare)

Before handling Protected Health Information (PHI):

  • Execute a BAA (Business Associate Agreement) with Twilio — contact your account manager or submit a sales request if you don't have one
  • Encrypt all recordings containing PHI
  • Minimize PHI in TTS — don't speak full patient details via <Say>
  • Rotate API keys on a regular schedule
  • Restrict access to recordings and transcripts

---

Fraud Prevention
SMS Pumping Protection

Attackers trigger thousands of OTP messages to premium-rate numbers, generating toll charges.

Layered defense:

  1. Twilio Verify Fraud Guard — built-in fraud detection (enable on Verify Service)
  2. Lookup pre-check — call twilio-lookup-phone-intelligence to check line type + SMS pumping risk score before sending
  3. Geo-permissions — restrict SMS/voice to countries where you have customers (Console > Messaging > Geo Permissions)
  4. Rate limiting — limit verification attempts per IP, per phone number, per time window
Geo-Permissions

Restrict which countries can receive messages or calls from your account:

  • Disable all countries you don't serve (SMS and Voice separately)
  • Re-enable only as needed — configure in Console
  • This is the single most effective anti-fraud measure for SMS pumping

SMS pumping impact: Incidents can climb into tens of thousands of dollars. Twilio does not publish most-targeted prefixes — the general guidance is to restrict message termination to countries where you do business via geo-permissions. Customers using Fraud Guard can view estimated fraud savings in their Fraud Guard reports.

---

Common Mistakes
  1. Auth Token in code — Pushed to GitHub, leaked. Use environment variables + API keys.
  2. No webhook validation — Attackers can send fake webhook requests to your endpoints.
  3. PCI Mode on main account — Irreversible. Use a sub-account for payment use cases.
  4. No geo-permissions — Account is open to SMS pumping from any country.
  5. Auth Token rotation without planning — Breaks all integrations using AccountSID:AuthToken and webhook signature validation simultaneously. API keys are unaffected.

---

Credential Rotation (Zero-Downtime)

Both API keys and Auth Tokens follow the same workflow:

  1. Create secondary — generate a new API key (or note the new Auth Token)
  2. Operationalize secondary — deploy the new credential to all services
  3. Promote secondary to primary — verify all traffic uses the new credential
  4. Delete old primary — revoke the previous credential

Manage keys at: https://console.twilio.com/account/keys-credentials/api-keys (per account).

Key enabler: use a secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.) to inject credentials at runtime. This makes rotation near-instantaneous with no downtime — no code changes, no redeployments. Organizations that hard-code credentials into repos, deployment scripts, or .env files must manually update every location before deleting the old key.

For ISVs managing many sub-accounts, automate this with the API Keys REST API across accounts.

---

Next Steps
  • Credential setup and API key management: twilio-iam-auth-setup
  • Webhook security and signature validation: twilio-webhook-architecture
  • Account structure and sub-accounts: twilio-account-setup
  • Phone intelligence for fraud scoring: twilio-lookup-phone-intelligence
  • Traffic compliance rules: twilio-compliance-traffic
Install

Planning skill that interrogates your use case before any code is written, then recommends the right Twilio Conversations stack — ConversationRelay, Memory, Intelligence, Orchestrator, TaskRouter — and the implementation skills to follow.

71 views

The rules that apply to live Twilio traffic — TCPA consent tiers, quiet hours and DNC, GDPR deletion rights, PCI DSS call recording, HIPAA, FDCPA, CAN-SPAM, WhatsApp policy and SHAKEN/STIR — with a consent-management pattern to implement.

Browse all skills →