SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场sinch-authentication

sinch-authentication

安全与审计

查看项目

更新于 10-16 11:29

技能介绍

用途

Sinch Authentication 是一个跨产品的凭证配置与认证技能，覆盖所有 Sinch API 的凭据设置与身份验证。它帮助确定正确的认证模型，并提供 curl 示例、SDK 初始化代码以及常见认证错误的排查方法。

如果用户尚未指定正在集成的 Sinch 产品，应先询问，因为认证模型取决于具体产品。

主要能力：识别认证模型

根据 Sinch 产品确定适用的认证模型：

  • 项目级（Basic 或 OAuth2）：Conversation API、Numbers、Fax、EST、10DLC、Number Lookup、Provisioning。需要 Project ID + Key ID + Key Secret。
  • 应用级（Basic 或签名请求）：Voice API、Verification API、In-App Calling SDK。需要 Application Key + Application Secret。
  • API key：Mailgun。需要 API Key（用户名为字面值 api）。

注意：Voice/Verification 凭据是与项目 Access Keys 完全独立的凭据集（来自不同的仪表盘页面和认证模型）。在多产品 SDK 客户端中，可以同时提供两组凭据，但不能相互替代。

获取凭据

  • 项目级：Dashboard > Settings > Access Keys，创建 Key ID + Key Secret。Project ID 位于仪表盘顶部。
  • 应用级：Dashboard > Voice > Apps 或 Verification > Apps，创建 Application Key + Application Secret。
  • Mailgun：https://app.mailgun.com/settings/api_security

Key Secret 只会在创建时显示一次，请安全保存。在发起 API 调用前，应将凭据加载到环境变量中，绝不要直接嵌入命令或代码：

# Project-scoped APIs (Conversation, Numbers, Fax, etc.)
export SINCH_PROJECT_ID="your-project-id"
export SINCH_KEY_ID="your-key-id"
export SINCH_KEY_SECRET="your-key-secret"

# Application-scoped APIs (Voice, Verification)
export SINCH_APP_KEY="your-application-key"
export SINCH_APP_SECRET="your-application-secret"

# Mailgun
export MAILGUN_API_KEY="your-mailgun-api-key"
export MAILGUN_DOMAIN="your-domain.com"

使用方式：进行认证

项目级 API

OAuth2（推荐）——用凭据换取 bearer token：

curl -X POST \
  https://auth.sinch.com/oauth2/token \
  -u "$SINCH_KEY_ID:$SINCH_KEY_SECRET"
  -d grant_type=client_credentials \

响应 JSON 包含 access_token 字段，这就是用作 bearer token 的 JWT：

{ "access_token": "eyJ...", "token_type": "bearer", "expires_in": 3600 }

不要自行铸造 JWT。上述 access_token 由 Sinch 的认证服务器签发和签名。本地签名的 JWT（例如 jsonwebtoken.sign({ iss: keyId }, keySecret, { algorithm: "HS256" })) 会被所有 Sinch API 以 HTTP 401 拒绝。始终向 token 端点 POST grant_type=client_credentials，并原样使用返回的 access_token。

在后续请求中使用它（3600 秒后过期）：

curl -X GET \
  "https://numbers.api.sinch.com/v1/projects/$SINCH_PROJECT_ID/activeNumbers" \
  -H "Authorization: Bearer $SINCH_ACCESS_TOKEN"

令牌端点 https://auth.sinch.com/oauth2/token 适用于所有项目级 API，包括 Conversation 和 Template Management 等区域化 API。

Basic 认证（仅限快速测试）——受支持但不建议用于生产（有严格速率限制）。将 Key ID 作为用户名、Key Secret 作为密码：

curl -X GET \
  "https://numbers.api.sinch.com/v1/projects/$SINCH_PROJECT_ID/activeNumbers" \
  -u "$SINCH_KEY_ID:$SINCH_KEY_SECRET"

生产负载应始终优先使用 OAuth2 bearer token——Basic 认证速率限制更低，且每次请求都会暴露凭据。

Voice、Verification 与 In-App Calling

使用 Basic 认证（原型开发）——Application Key 作为用户名，Application Secret 作为密码：

curl -X POST \
  "https://calling.api.sinch.com/calling/v1/callouts" \
  -u "$SINCH_APP_KEY:$SINCH_APP_SECRET"

或使用 HMAC 签名请求（生产）——参见签名算法文档：

  • Voice：https://developers.sinch.com/docs/voice/api-reference/authentication/signed-request.md
  • Verification：https://developers.sinch.com/docs/verification/api-reference/authentication/application-signed-request.md

Verification API 还支持 Public Authentication（较弱，仅限客户端 SDK）。

Mailgun

curl -X GET \
  "https://api.mailgun.net/v3/$MAILGUN_DOMAIN/messages" \
  -s --user "api:$MAILGUN_API_KEY"

SDK 安装

SDK 安装与客户端初始化请参见 sinch-sdks 技能。

注意事项

  • OAuth2 令牌 3600 秒后过期。SDK 会自动刷新；使用 curl 时需在过期前重新请求。
  • Voice/Verification 使用应用凭据，而非项目 Access Keys。这是来自不同仪表盘页面的两套完全独立的凭据集。
  • Key Secret 只显示一次。若丢失，请创建新的 Access Key。
  • 绝不要硬编码凭据——始终从环境变量或密钥管理器加载 Key ID、Key Secret 和 API key。不要将凭据嵌入源代码、shell 历史或代理指令中。
  • Basic 认证有速率限制——生产环境使用 OAuth2 bearer token 以获得更高吞吐量。

排查常见错误

  • Conversation/Numbers API 返回 401 Unauthorized：凭据错误或令牌过期。核实 Access Keys 中的 Key ID，并使用创建时保存的 Key Secret；若密钥已丢失，创建新的 Access Key 并重新请求 OAuth2 令牌。同时检查 WWW-Authenticate 响应头以获取详情（例如 invalid token、expired token 或 invalid client）。
  • Voice/Verification 返回 401 Invalid Signature：Application Key/Secret 错误或签名有误。核实 Voice > Apps 中的应用凭据；确保 HMAC 签名符合算法规范。
  • OAuth2 令牌对 Numbers 有效但对 Conversation 失败：API base URL 区域错误。确保 API base URL 与应用区域匹配（例如欧盟应用使用 eu.conversation.api.sinch.com）。
  • 403 Forbidden：密钥没有访问该项目/产品的权限。检查仪表盘中的 Access Key 范围；确保 Project ID 正确。

参考链接

需认证的仪表盘链接供人工操作者使用：Sinch Dashboard（https://dashboard.sinch.com）、Access Keys（https://dashboard.sinch.com/settings/access-keys）、Voice Apps（https://dashboard.sinch.com/voice/apps）、Verification Apps（https://dashboard.sinch.com/verification/apps）、Mailgun API Keys（https://app.mailgun.com/settings/api_security）。

公开文档链接：Voice 认证文档（https://developers.sinch.com/docs/voice/api-reference/authentication.md）、Verification 认证文档（https://developers.sinch.com/docs/verification/api-reference/authentication.md）、In-App Calling（https://developers.sinch.com/docs/in-app-calling/overview.md）、如何创建 Access Keys（https://community.sinch.com/t5/Conversation-API/How-do-I-create-new-Access-Keys-for-use-with-the-Conversation/ta-p/8120）、Sinch 文档（https://developers.sinch.com/llms.txt）。