用途:帮助开发者为 Twilio 集成选择正确的认证方式并正确实现,避免凭证泄露。
主要能力与选型:Auth Token 仅用于本地测试,永久有效且不可单独撤销;API Key + Secret 是生产服务端标准,可单独撤销;OAuth2 Bearer Token 用于生产服务端增强场景,1 小时过期;Access Token(JWT)用于浏览器/移动端 SDK,最长 24 小时。决策:快速原型用 Auth Token,部署前换 API Key;生产服务端用 API Key 或 OAuth2;客户端连接由服务端生成 Access Token;免计费测试用测试凭证的魔法号码。
使用方式:API Key 在控制台创建,分 Main(仅控制台)、Standard(除 /Accounts 和 /Keys 外全资源)、Restricted(最多 100 项权限)三类。Python 用 Client(os.environ["TWILIO_API_KEY"], os.environ["TWILIO_API_SECRET"], os.environ["TWILIO_ACCOUNT_SID"]);Node.js 用 require("twilio")(process.env.TWILIO_API_KEY, process.env.TWILIO_API_SECRET, { accountSid: process.env.TWILIO_ACCOUNT_SID })。OAuth2 先在控制台建 OAuth App,再向 https://oauth.twilio.com/v2/token 发 POST,带 client_id、client_secret、grant_type=client_credentials,返回 access_token、Bearer、expires_in 3600,之后以 Authorization: Bearer 调用 API。Access Token 用 twilio.jwt.access_token 生成,可加 VoiceGrant、VideoGrant、ChatGrant、SyncGrant。测试凭证位于控制台,魔法号码有 +15005550006(有效)、+15005550001(无效,错误 21211)、+15005550007(无短信,错误 21612)。
限制:Standard 密钥不能访问 /Accounts 或 /Keys(返回 20003);v2010 API 无法创建受限密钥;受限密钥不能生成 Access Token;Access Token 不可单独撤销,删除签发密钥可全部撤销;OAuth2 仅支持 client_credentials,无刷新令牌,1 小时过期需自行刷新;API Key Secret 仅在创建时显示;轮换 Auth Token 不影响 API Key,但会失效依赖 AccountSID:AuthToken 的集成并破坏 Webhook 签名验证;测试凭证仅支持 Messages、Calls、IncomingPhoneNumbers、Lookups 四个端点,其余返回 403。SDK 对 OAuth2 的最低版本:Java 10.6.0、C#/.NET 7.6.0、Node.js 5.4.0、Python 9.4.1、Ruby 7.4.0、PHP 8.5.0、Go 1.25.1。