Update to Twilio Developer Kit

{
  "name": "twilio-security-api-auth",
  "description": "Choose the right Twilio authentication method and implement it correctly. Covers Auth Token (testing only), API Keys (production standard), OAuth2 client_credentials (time-limited bearer tokens), Access Tokens (client-side SDKs), and test credentials. Use this skill before making any Twilio API calls in production.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 229
    }
  ],
  "skill_md_contents": "---\nname: twilio-security-api-auth\ndescription: >\n  Choose the right Twilio authentication method and implement it correctly.\n  Covers Auth Token (testing only), API Keys (production standard), OAuth2\n  client_credentials (time-limited bearer tokens), Access Tokens (client-side\n  SDKs), and test credentials. Use this skill before making any Twilio API\n  calls in production.\n---\n\n## Overview\n\nTwilio supports four authentication methods. Choosing the wrong one is a security risk — Auth Tokens in production code are the most common credential leak.\n\n| Method | Use for | Token lifetime | Revocable individually |\n|--------|---------|---------------|----------------------|\n| **Auth Token** | Local testing only | Permanent (until rotated) | No — rotation breaks ALL API keys |\n| **API Key + Secret** | Production server-side | Permanent (until deleted) | Yes |\n| **OAuth2 Bearer Token** | Production server-side (enhanced) | 1 hour | Expires automatically |\n| **Access Token (JWT)** | Client-side SDKs (Voice, Video, Chat) | Up to 24 hours | No — delete issuing API key |\n\n**Decision framework:**\n- **Building a quick prototype?** → Auth Token (but switch to API Key before deploying)\n- **Production server-side code?** → API Key + Secret (simplest production auth) or OAuth2 (time-limited tokens)\n- **Browser/mobile client needs to connect?** → Access Token (JWT) generated server-side\n- **Running tests without charges?** → Test credentials with magic numbers\n\n---\n\n## API Key Authentication (Production Standard)\n\n**Create:** Console → Account → API keys & tokens → Create API key\n\n| Key type | Access | Create via |\n|----------|--------|-----------|\n| **Main** | Full account access | Console only |\n| **Standard** | All resources except /Accounts and /Keys endpoints | Console or API |\n| **Restricted** | Specific resources only (up to 100 permissions) | Console or v1 IAM API only |\n\n**Python**\n```python\nimport os\nfrom twilio.rest import Client\n\nclient = Client(\n    os.environ[\"TWILIO_API_KEY\"],      # SKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n    os.environ[\"TWILIO_API_SECRET\"],\n    os.environ[\"TWILIO_ACCOUNT_SID\"]   # required as third argument\n)\n```\n\n**Node.js**\n```node\nconst client = require(\"twilio\")(\n    process.env.TWILIO_API_KEY,\n    process.env.TWILIO_API_SECRET,\n    { accountSid: process.env.TWILIO_ACCOUNT_SID }\n);\n```\n\n---\n\n## OAuth2 Authentication (Client Credentials)\n\nTime-limited bearer tokens that expire after 1 hour. More secure than permanent API keys for server-to-server communication.\n\n### Step 1 — Create an OAuth App\n\nCreate an OAuth App in the Twilio Console to get a Client ID and Client Secret.\n\n### Step 2 — Request a Bearer Token\n\n**cURL**\n```bash\ncurl -X POST 'https://oauth.twilio.com/v2/token' \\\n  -H 'Content-Type: application/x-www-form-urlencoded' \\\n  -d 'client_id={ClientID}' \\\n  -d 'client_secret={ClientSecret}' \\\n  -d 'grant_type=client_credentials'\n```\n\n**Response:**\n```json\n{\n    \"access_token\": \"{BearerToken}\",\n    \"token_type\": \"Bearer\",\n    \"expires_in\": 3600\n}\n```\n\n### Step 3 — Use the Bearer Token\n\n```bash\ncurl 'https://api.twilio.com/2010-04-01/Accounts/{AccountSID}/Messages.json' \\\n  -H 'Authorization: Bearer {BearerToken}'\n```\n\n### SDK Support\n\nOAuth2 is supported in all Twilio SDKs:\n\n| Language | Minimum version |\n|----------|----------------|\n| Java | 10.6.0 |\n| C#/.NET | 7.6.0 |\n| Node.js | 5.4.0 |\n| Python | 9.4.1 |\n| Ruby | 7.4.0 |\n| PHP | 8.5.0 |\n| Go | 1.25.1 |\n\n**Docs:** [OAuth access tokens](https://www.twilio.com/docs/iam/oauth-apps/oauth-access-token) | [Segment OAuth connections](https://www.twilio.com/docs/segment/connections/oauth)\n\n---\n\n## Access Tokens (Client-Side SDKs)\n\nShort-lived JWTs for authenticating browser/mobile clients. Generate server-side, pass to the client.\n\n**Python**\n```python\nfrom twilio.jwt.access_token import AccessToken\nfrom twilio.jwt.access_token.grants import VoiceGrant\n\ntoken = AccessToken(\n    os.environ[\"TWILIO_ACCOUNT_SID\"],\n    os.environ[\"TWILIO_API_KEY\"],\n    os.environ[\"TWILIO_API_SECRET\"],\n    identity=\"user-123\",\n    ttl=3600\n)\ntoken.add_grant(VoiceGrant(outgoing_application_sid=\"APxxxx\"))\nprint(token.to_jwt())\n```\n\nGrant types: `VoiceGrant`, `VideoGrant`, `ChatGrant` (Conversations), `SyncGrant`\n\n---\n\n## Test Credentials\n\nMake API calls without charges. Find at Console → Account → API keys & tokens → Test credentials.\n\nMagic numbers: `+15005550006` (valid), `+15005550001` (invalid, error 21211), `+15005550007` (no SMS, error 21612)\n\n---\n\n## CANNOT\n\n- **Standard keys cannot access /Accounts or /Keys endpoints** — Returns 20003 (401). Use Auth Token or Main key.\n- **Cannot create restricted keys via v2010 API** — Silently creates a standard key instead. Use v1 IAM API.\n- **Restricted keys cannot generate Access Tokens** — Only Standard and Main keys can.\n- **Cannot revoke individual Access Tokens** — Valid until expiration (max 24h). Delete the issuing API key to revoke all.\n- **OAuth2 only supports `client_credentials` grant** — No refresh tokens, no authorization code flow.\n- **OAuth2 tokens expire after 1 hour** — Your application must handle token refresh.\n- **API Key Secret shown only at creation** — Cannot be retrieved afterward.\n- **Auth Token rotation breaks ALL API keys** — One-way door. This is why you should use API keys from day one.\n- **Test credentials work with only 4 endpoints** — Messages, Calls, IncomingPhoneNumbers, Lookups. All others return 403.\n\n---\n\n## Next Steps\n\n- **Account setup and sub-accounts:** `twilio-account-setup`\n- **HIPAA account configuration:** `twilio-security-compliance-hipaa`\n- **Webhook signature validation:** `twilio-webhook-architecture`\n- **Credential security patterns:** `twilio-security-hardening`\n"
}