Back to Details

sinch-authentication

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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 ModelProductsCredentials Needed
Project-scoped (Basic or OAuth2)Conversation API, Numbers, Fax, EST, 10DLC, Number Lookup, ProvisioningProject ID + Key ID + Key Secret
Application-scoped (Basic or Signed)Voice API, Verification API, In-App Calling SDKsApplication Key + Application Secret
API keyMailgunAPI 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、ProvisioningProject ID + Key ID + Key Secret
应用级（基础认证或签名认证）Voice API、Verification API、In-App Calling SDKsApplication Key + Application Secret
API密钥MailgunAPI 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

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

故障排查

ErrorCauseFix
401 Unauthorized
on Conversation/Numbers API		Wrong credentials or expired tokenVerify 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 errorVerify app credentials from Voice > Apps; ensure HMAC signing matches the algorithm spec
OAuth2 token works for Numbers but fails for ConversationWrong API base URL regionEnsure 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/productCheck 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 APIAPI基础URL区域错误确保API基础URL与应用的区域匹配（例如，欧盟地区的应用使用
eu.conversation.api.sinch.com
）
403 Forbidden
密钥无此项目/产品的访问权限在控制台中检查访问密钥的权限范围；确保Project ID正确

Links

相关链接

Dashboard links below require authentication and are intended for human operators. Agents should rely on public docs for procedural guidance and treat dashboard URLs as navigational references only.
Authenticated Console Links (human operators):
Public Documentation Links (agent-friendly):
以下控制台链接需要认证，仅供人工操作人员使用。智能助手应依靠公开文档获取流程指导，仅将控制台URL作为导航参考。
需认证的控制台链接（人工操作人员）：
公开文档链接（智能助手适用）：