sinch-authentication

Sinch 身份验证

覆盖所有 Sinch API 的通用技能，涵盖凭据设置和身份验证。确定正确的身份验证模式，提供 curl 示例、SDK 初始化代码，以及常见身份验证错误的故障排除方法。

Agent 指令

策略门控 sinch-shared-policy@5（sha256:4864cf0fa8d6）： 以下策略摘要具有约束力，必须照此执行。在实施或实时执行之前，每段对话只需阅读一次完整的 Sinch 共享策略；如果已加载此完全相同的 ID/版本/指纹，则跳过；如果版本更新或指纹不同，则阅读。此技能的规范操作路由位于其 Agent 指令和链接部分。

Sinch 策略摘要（具有约束力）：

1. 每段对话加载一次共享策略；跳过具有相同 ID/版本/指纹的重复副本。
2. 根据请求和工作区推断产品、语言、地区和环境；只有遇到真正的阻碍时，才合并为一个问题提问。优先使用官方 Sinch SDK，除非请求或工作区另有决定，或没有官方 SDK 支持该语言或操作。
3. 代码生成的批准不等于执行批准。对每项操作分类（只读／可逆／计费／破坏性），并在执行计费或破坏性调用前获得明确批准。
4. B 级事实——端点路径、方法、字段名称、枚举值、限制、Webhook 载荷、签名算法、SDK 签名——使用前必须在当前会话中获取准确的规范文档。
5. 随附脚本、参考资料和示例属于 C 级：仅供说明，绝不能作为架构规范依据。切勿将示例值提升为生产默认值。
6. 如果路由未解决或规范文档获取失败，按顺序沿解析阶梯逐步处理——重新搜索已获取的文档（原始内容，不是摘要）、查阅 https://developers.sinch.com/llms.txt、访问第一方链接、重试一次——之后再安全拒绝。切勿猜测文档 URL；切勿用记忆、搜索摘要或随附文件替代。
7. 维护证据台账，将每个已获取的来源映射到其授权的字段和声明。
8. 限制所有轮询和重试（退避、抖动、硬性上限）；在重试计费或破坏性操作前检查状态；超时应报告为状态未知，而非失败。
9. 分别报告验证级别（lint → 单元测试 → 模拟契约测试 → 沙盒 → 实时 → 端到端）；HTTP 2xx 并不能证明已交付。说明未执行的验证级别。
10. 仅加载负责该行为的最小技能集；如果所需技能不可用，指出其名称并停止，不要自行臆断指令。

如果用户没有说明要集成哪种 Sinch 产品，请先询问——身份验证模式取决于产品。使用步骤 1 中的决策表，选择正确的凭据。

信息来源 — 加载内容及其权威性

此技能包含两类可靠性不相同的内容。请按以下优先级处理：

1. developers.sinch.com 上的规范文档（权威）。 此技能中的 .md 文档链接是请求/响应架构、字段名称及嵌套结构、枚举值、签名/身份验证方案和限制的唯一事实来源。在编写用于构造有效负载、验证签名或解析回调/响应的代码之前，请先获取相应的链接文档，并确认其中的确切结构。根据安全/URL 政策，可以获取 developers.sinch.com 的第一方 URL。绝不要虚构、猜测或根据模式推断文档 URL——只能获取此技能中逐字写出的文档 URL，或通过已获取页面中的链接访问的 URL；域名可信，并不意味着猜测的路径真实存在。
2. 此 SKILL.md 中的表格、字段列表和代码片段（摘要——非权威）。 这些内容为你提供指引，并指向相应的规范文档；它们可能未及时更新、遗漏字段，或简化嵌套结构。请用它们来确定要构建什么以及要打开哪份文档。未经第 1 级文档确认，切勿将此文件中的字段名称、嵌套结构、编码或枚举值照搬到已发布的代码中。如果某项细节只出现在摘要中，请将其视为未经验证，并明确说明。

快速规则：编写代码 → 加载文档。 绝不要引用仅在摘要中看到的确切字段、标头、枚举值或编码。

步骤 1：确定身份验证模型

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

身份验证模型	产品	所需凭据
项目级（Basic 或 OAuth2）	Conversation API、Numbers、Fax、EST、10DLC、Number Lookup、Provisioning	Project ID + Key ID + Key Secret
应用级（Basic 或 Signed）	Voice API、Verification API、In-App Calling SDKs	Application Key + Application Secret
API 密钥	Mailgun	API Key（用户名为字面值 api）

Voice/Verification 凭据与项目 Access Keys 是两套独立的凭据（位于不同的控制面板页面，且身份验证模型不同）。在多产品 SDK 客户端中，可以同时提供两套凭据，但不要互相替代。

步骤 2：获取凭据

• 项目级：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 Secrets——创建时仅显示一次。

在调用 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"

步骤 3：进行身份验证

项目级 API

OAuth2（推荐） — 交换凭据以获取承载令牌：

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

（仅为摘要 — 实现前，请对照权威的 Sinch Docs 文档确认准确名称、编码和枚举值。）

响应 JSON 包含一个 access_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。务必向令牌端点 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 auth（仅用于快速测试） — 支持，但不建议用于生产环境（受到严格的速率限制）。将 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 承载令牌 — Basic auth 的速率限制更低，并且每个请求都会暴露凭据。

Voice、Verification 和应用内通话

使用 Basic auth（原型开发）— 将 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 也支持公开身份验证（安全性较弱，仅适用于客户端 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 密钥。不要将凭据嵌入源代码、Shell 历史记录或 Agent 指令中。
• Basic auth 有速率限制 — 生产环境请使用 OAuth2 承载令牌，以获得更高的吞吐量。

故障排除

错误	原因	修复方法
401 Unauthorized（Conversation/Numbers API）	凭据错误或令牌已过期	验证 Access Keys 中的 Key ID，并使用创建时保存的 Key Secret；如果密钥已丢失，请创建新的 Access Key 并重新请求 OAuth2 令牌。也请检查 WWW-Authenticate 响应标头以了解详情（例如，令牌无效、令牌过期或客户端无效）。
401 Invalid Signature（Voice/Verification）	Application Key/Secret 错误或签名错误	在 Voice > Apps 中验证应用凭据；确保 HMAC 签名符合算法规范
OAuth2 令牌适用于 Numbers，但在 Conversation 中失败	API 基础 URL 区域错误	确保 API 基础 URL 与应用的区域相符（例如，EU 应用使用 eu.conversation.api.sinch.com）
403 Forbidden	Key 无权访问此项目/产品	在仪表板中检查 Access Key 范围；确保 Project ID 正确

链接

以下控制台链接需要身份验证，供人工操作人员使用。Agent 应参考公开文档获取操作指南，并且仅将控制台 URL 作为导航参考。

已通过身份验证的控制台链接（供人工操作人员使用）：

• 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

公开文档链接（适用于 Agent）：

• Project OAuth Docs：https://developers.sinch.com/docs/numbers/api-reference/authentication/oauth
• Voice Auth Docs：https://developers.sinch.com/docs/voice/api-reference/authentication.md
• Verification Auth Docs：https://developers.sinch.com/docs/verification/api-reference/authentication.md
• Mailgun Auth Docs：https://documentation.mailgun.com/docs/mailgun/api-reference/mg-auth.md
• In-App Calling：https://developers.sinch.com/docs/in-app-calling/overview.md
• How to Create 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 Docs：https://developers.sinch.com/llms.txt