Sinch Authentication

Sinch 认证

Cross-cutting skill that covers credential setup and authentication for all Sinch APIs. Determines the correct auth model, provides curl examples, SDK init code, and troubleshooting for common auth errors.

这是一项通用技能，涵盖所有Sinch API的凭证设置与认证流程。可确定正确的认证模型，提供curl示例、SDK初始化代码，以及常见认证错误的排查方案。

Agent Instructions

智能助手操作说明

If the user hasn't specified which Sinch product they're integrating, ask first — the auth model depends on the product. Use the decision table in Step 1 to route to the correct credentials.

如果用户未指定要集成的Sinch产品，请先询问——认证模型取决于具体产品。使用步骤1中的决策表来选择正确的凭证类型。

Step 1: Identify the Auth Model

步骤1：确定认证模型

Determine which model applies based on the Sinch product:

Auth Model	Products	Credentials Needed
Project-scoped (Basic or OAuth2)	Conversation API, Numbers, Fax, EST, 10DLC, Number Lookup, Provisioning	Project ID + Key ID + Key Secret
Application-scoped (Basic or Signed)	Voice API, Verification API, In-App Calling SDKs	Application Key + Application Secret
API key	Mailgun	API Key (username is literal `api` )

Voice/Verification credentials are a separate credential set from project Access Keys (different dashboard pages and auth models). In multi-product SDK clients, you may provide both sets together, but do not substitute one set for the other.

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

认证模型	适用产品	所需凭证
项目级（基础认证或OAuth2）	Conversation API、Numbers、Fax、EST、10DLC、Number Lookup、Provisioning	Project ID + Key ID + Key Secret
应用级（基础认证或签名认证）	Voice API、Verification API、In-App Calling SDKs	Application Key + Application Secret
API密钥	Mailgun	API Key（用户名为固定值 `api` ）

Voice/Verification的凭证是独立的凭证集，与项目访问密钥不同（来自控制台的不同页面，采用不同的认证模型）。在多产品SDK客户端中，可同时提供这两类凭证，但不可互相替代。

Step 2: Get Credentials

步骤2：获取凭证

Project-scoped: Dashboard > Settings > Access Keys → creates Key ID + Key Secret. Project ID is at the top of the dashboard.
Application-scoped: Dashboard > Voice > Apps or Verification > Apps → creates Application Key + Application Secret.
Mailgun: https://app.mailgun.com/settings/api_security

Store Key Secrets securely — they are shown only once at creation.

项目级：控制台 > 设置 > 访问密钥 → 创建Key ID + Key Secret。Project ID可在控制台顶部查看。
应用级：控制台 > Voice > 应用或 Verification > 应用 → 创建Application Key + Application Secret。
Mailgun：https://app.mailgun.com/settings/api_security

请安全存储Key Secret——仅在创建时显示一次。

Step 3: Authenticate

步骤3：进行认证

Project-Scoped APIs

项目级API

Use Basic auth (simplest) — Key ID as username, Key Secret as password:

bash

curl -u YOUR_KEY_ID:YOUR_KEY_SECRET \
  https://numbers.api.sinch.com/v1/projects/{PROJECT_ID}/activeNumbers

Or use OAuth2 — exchange credentials for a bearer token:

bash

curl -X POST https://auth.sinch.com/oauth2/token \
  -d grant_type=client_credentials \
  -u YOUR_KEY_ID:YOUR_KEY_SECRET

The response JSON contains an

access_token

field — this is the JWT to use as the bearer token:

json

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

Use it in subsequent requests:

Authorization: Bearer {access_token}

(expires in 3600s).

The token endpoint

https://auth.sinch.com/oauth2/token

works for all project-scoped APIs, including regional ones like Conversation and Template Management. Regional aliases (

us.auth.sinch.com

,

eu.auth.sinch.com

) also exist but are not required — the global URL issues tokens valid for any region.

使用基础认证（最简单）——将Key ID作为用户名，Key Secret作为密码：

bash

curl -u YOUR_KEY_ID:YOUR_KEY_SECRET \
  https://numbers.api.sinch.com/v1/projects/{PROJECT_ID}/activeNumbers

或使用OAuth2——通过凭证换取Bearer令牌：

bash

curl -X POST https://auth.sinch.com/oauth2/token \
  -d grant_type=client_credentials \
  -u YOUR_KEY_ID:YOUR_KEY_SECRET

响应JSON包含

access_token

字段——这是用作Bearer令牌的JWT：

json

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

在后续请求中使用：

Authorization: Bearer {access_token}

（有效期3600秒）。

令牌端点

https://auth.sinch.com/oauth2/token

适用于所有项目级API，包括Conversation和模板管理等区域级API。也存在区域别名（

us.auth.sinch.com

、

eu.auth.sinch.com

），但并非必需——全局URL颁发的令牌在任何区域均有效。

Voice, Verification & In-App Calling

Voice、Verification与In-App Calling

Use Basic auth (prototyping) — Application Key as username, Application Secret as password:

bash

curl -X POST -u YOUR_APP_KEY:YOUR_APP_SECRET \
  https://calling.api.sinch.com/calling/v1/callouts

Or use HMAC Signed Requests (production) — see signing algorithm docs:

Verification API also supports Public Authentication (weak, client-side SDK only).

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

bash

curl -X POST -u YOUR_APP_KEY:YOUR_APP_SECRET \
  https://calling.api.sinch.com/calling/v1/callouts

或使用HMAC签名请求（生产环境）——请查看签名算法文档：

Verification API还支持公开认证（安全性较弱，仅适用于客户端SDK）。

Mailgun

bash

curl -s --user 'api:YOUR_MAILGUN_API_KEY' \
  https://api.mailgun.net/v3/{DOMAIN}/messages

bash

curl -s --user 'api:YOUR_MAILGUN_API_KEY' \
  https://api.mailgun.net/v3/{DOMAIN}/messages

SDK Initialization

SDK初始化

For SDK-specific init code, use the language-specific references:

Node.js: references/sdk-init-node.md
Python: references/sdk-init-python.md
Java: references/sdk-init-java.md
.NET: references/sdk-init-dotnet.md
In-App Calling (Browser): references/sdk-init-in-app-calling-browser.md
In-App Calling (iOS): references/sdk-init-in-app-calling-ios.md
In-App Calling (Android): references/sdk-init-in-app-calling-android.md

If language is unknown, ask first. The SDKs handle token refresh automatically.

如需特定语言的SDK初始化代码，请参考对应语言的文档：

Node.js: references/sdk-init-node.md
Python: references/sdk-init-python.md
Java: references/sdk-init-java.md
.NET: references/sdk-init-dotnet.md
In-App Calling（浏览器）: references/sdk-init-in-app-calling-browser.md
In-App Calling（iOS）: references/sdk-init-in-app-calling-ios.md
In-App Calling（Android）: references/sdk-init-in-app-calling-android.md

若未指定语言，请先询问用户。SDK会自动处理令牌刷新。

Gotchas

注意事项

OAuth2 tokens expire in 3600s. SDKs auto-refresh; for curl, re-request before expiry.
Regional API URLs matter for Conversation/Template APIs: The API base URL must match the region where the app was created (e.g.,
```
us.conversation.api.sinch.com
```
,
```
eu.conversation.api.sinch.com
```
). The OAuth token endpoint, however, is always
```
https://auth.sinch.com/oauth2/token
```
.
Voice/Verification use application credentials, not project Access Keys. These are entirely separate credential sets from different dashboard pages.
Key Secrets are shown only once. If lost, create a new Access Key.

OAuth2令牌有效期为3600秒。SDK会自动刷新；使用curl时，请在过期前重新请求。
Conversation/模板API的区域URL至关重要：API基础URL必须与应用创建时的区域匹配（例如，
```
us.conversation.api.sinch.com
```
、
```
eu.conversation.api.sinch.com
```
）。但OAuth令牌端点始终为
```
https://auth.sinch.com/oauth2/token
```
。
Voice/Verification使用应用凭证，而非项目访问密钥。这是完全独立的凭证集，来自控制台的不同页面。
Key Secret仅显示一次。若丢失，请创建新的访问密钥。

Troubleshooting

故障排查

Error	Cause	Fix
`401 Unauthorized` on Conversation/Numbers API	Wrong credentials or expired token	Verify Key ID from Access Keys and use the Key Secret saved at creation time; if the secret was lost, create a new Access Key and re-request an OAuth2 token. Also inspect the `WWW-Authenticate` response header for details (for example, invalid token, expired token, or invalid client).
`401 Invalid Signature` on Voice/Verification	Wrong Application Key/Secret or signing error	Verify app credentials from Voice > Apps; ensure HMAC signing matches the algorithm spec
OAuth2 token works for Numbers but fails for Conversation	Wrong API base URL region	Ensure the API base URL matches the app's region (e.g., `eu.conversation.api.sinch.com` for EU apps)
`403 Forbidden`	Key doesn't have access to this project/product	Check Access Key scope in dashboard; ensure correct Project ID

错误	原因	解决方法
`401 Unauthorized` （Conversation/Numbers API）	凭证错误或令牌过期	验证访问密钥中的Key ID是否正确，并使用创建时保存的Key Secret；若密钥丢失，请创建新的访问密钥并重新请求OAuth2令牌。同时检查 `WWW-Authenticate` 响应头获取详细信息（例如，令牌无效、令牌过期或客户端无效）。
`401 Invalid Signature` （Voice/Verification）	Application Key/Secret错误或签名错误	验证Voice > 应用中的应用凭证是否正确；确保HMAC签名符合算法规范
OAuth2令牌可用于Numbers API，但无法用于Conversation API	API基础URL区域错误	确保API基础URL与应用的区域匹配（例如，欧盟地区的应用使用 `eu.conversation.api.sinch.com` ）
`403 Forbidden`	密钥无此项目/产品的访问权限	在控制台中检查访问密钥的权限范围；确保Project ID正确

sinch-authentication

Original

Translation

Sinch Authentication

Sinch 认证

Agent Instructions

智能助手操作说明

Step 1: Identify the Auth Model

步骤1：确定认证模型

Step 2: Get Credentials

步骤2：获取凭证

Step 3: Authenticate

步骤3：进行认证

Project-Scoped APIs

项目级API

Voice, Verification & In-App Calling

Voice、Verification与In-App Calling

Mailgun

Mailgun

SDK Initialization

SDK初始化

Gotchas

注意事项

Troubleshooting

故障排查

Links

相关链接