sinch-authentication

Sinch 認証

すべての Sinch API に共通する、認証情報の設定と認証を扱うスキルです。適切な認証モデルを判断し、curl の例、SDK の初期化コード、よくある認証エラーのトラブルシューティングを提供します。

エージェントへの指示

ポリシーゲート sinch-shared-policy@5（sha256:4864cf0fa8d6）： 以下のポリシーダイジェストは記載どおりに遵守する必要があります。実装または実環境での実行の前に、Sinch 共通ポリシーの全文を会話ごとに一度読み込んでください。この正確な ID／バージョン／フィンガープリントがすでに読み込まれている場合は省略し、バージョンが新しい場合、またはフィンガープリントが異なる場合は読み込んでください。このスキルで正規の操作ルートは、「エージェントへの指示」および「リンク」セクションに記載されています。

Sinch ポリシーダイジェスト（遵守必須）：

1. 会話ごとに共通ポリシーを一度読み込み、同じ ID／バージョン／フィンガープリントを持つ重複コピーは省略します。
2. リクエストとワークスペースからプロダクト、言語、リージョン、環境を推定し、実際に作業を阻む不明点がある場合に限り、質問をひとつにまとめて尋ねます。リクエストまたはワークスペースで別の方法が指定されている場合、あるいはその言語や操作に対応する公式 SDK がない場合を除き、公式の Sinch SDK を優先します。
3. コード生成の承認は実行の承認ではありません。各操作を（読み取り専用／取り消し可能／課金対象／破壊的）に分類し、課金対象または破壊的な呼び出しの前に明示的な承認を得ます。
4. Tier B の事実（エンドポイントパス、メソッド、フィールド名、列挙値、上限、Webhook ペイロード、署名アルゴリズム、SDK のシグネチャ）は、使用前に現在のセッションで該当する正規ドキュメントを取得する必要があります。
5. 同梱スクリプト、リファレンス、例は Tier C であり、説明用であってスキーマの根拠にはなりません。例の値を本番環境のデフォルト値として扱ってはいけません。
6. ルートが特定できない場合、または正規ドキュメントの取得に失敗した場合は、失敗として処理を打ち切る前に、解決手順を順番に進めてください。取得済みドキュメントを要約せずに再検索し、https://developers.sinch.com/llms.txt を参照し、ファーストパーティのリンクをたどり、もう一度再試行します。ドキュメント URL を推測してはいけません。記憶、検索スニペット、同梱ファイルで代用してはいけません。
7. 取得した各ソースと、そのソースが根拠となるフィールドや主張を対応付けたエビデンス台帳を維持します。
8. すべてのポーリングと再試行に上限を設けます（バックオフ、ジッター、ハード上限）。課金対象または破壊的な操作を再試行する前に状態を確認し、タイムアウトは失敗ではなく不明として報告します。
9. 検証レベル（lint → unit → mock contract → sandbox → live → end-to-end）は個別に報告します。HTTP 2xx で配信が証明されるわけではありません。実施していないレベルも明記します。
10. 動作の責任を持つ最小限のスキルセットのみを読み込みます。必要なスキルを利用できない場合は、そのスキル名を明示して停止し、指示を推測して補ってはいけません。

ユーザーが連携する Sinch プロダクトを指定していない場合は、まず確認してください。認証モデルはプロダクトによって異なります。適切な認証情報へ案内するには、ステップ 1 の判断表を使用してください。

信頼できる情報源 — 読み込むべき情報と、正とする情報

このスキルには、信頼性が異なる2 種類のコンテンツがあります。次の優先順位に従ってください。

1. developers.sinch.com の正式なドキュメント（権威ある情報源）。 このスキル内の .md ドキュメントへのリンクは、正確なリクエスト／レスポンスのスキーマ、フィールド名とネスト構造、列挙値、署名／認証方式、制限に関する唯一の信頼できる情報源です。ペイロードを構築するコードの作成、署名の検証、コールバック／レスポンスの解析を行う前に、リンク先の該当ドキュメントを取得し、正確な形式を確認してください。ファーストパーティの developers.sinch.com URL の取得は、セキュリティ／URL ポリシーで許可されています。ドキュメントの URL を推測したり、パターンから推定したりしてはいけません。このスキルにそのまま記載されているドキュメント URL、またはすでに取得したページ内のリンクをたどって到達した URL のみ取得してください。信頼できるドメインだからといって、推測したパスが実在するとは限りません。
2. この SKILL.md 自体の表、フィールド一覧、スニペット（要約 — 権威ある情報源ではありません）。 これらは概要を示し、適切な正式ドキュメントを案内するものです。内容が古くなっていたり、フィールドが省略されていたり、ネスト構造が簡略化されていたりする場合があります。何を作成し、どのドキュメントを開くかを決める際に使ってください。このファイルに記載されたフィールド名、ネスト構造、エンコーディング、列挙値を、Tier 1 のドキュメントで確認せずに出荷するコードへ転記してはいけません。詳細が要約にしか記載されていない場合は、未確認の情報として扱い、その旨を明示してください。

簡単なルール：コードを書く前に、ドキュメントを読み込むこと。 要約でしか確認していない正確なフィールド、ヘッダー、列挙値、エンコーディングを引用してはいけません。

Step 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 クライアントでは、両方のセットをまとめて指定できますが、一方をもう一方の代わりに使ってはいけません。

Step 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 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"

Step 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 により拒否されます。必ずトークンエンドポイントに grant_type=client_credentials を POST し、返された 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 は、Conversation や Template Management などのリージョン別 API を含む、すべてのプロジェクトスコープの 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 ベアラートークンを優先してください。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 Key ではなくアプリケーションの認証情報を使用します。 これらは別々のダッシュボードページにある、まったく異なる認証情報セットです。
• Key Secret は一度しか表示されません。紛失した場合は、新しい Access Key を作成してください。
• 認証情報をコードに直接記述しないでください。 Key ID、Key Secret、API キーは、必ず環境変数またはシークレットマネージャーから読み込んでください。認証情報をソースコード、シェル履歴、エージェントへの指示に埋め込まないでください。
• Basic 認証にはレート制限があります。 本番環境でより高い処理量が必要な場合は、OAuth2 ベアラートークンを使用してください。

トラブルシューティング

エラー	原因	解決方法
Conversation／Numbers API で 401 Unauthorized	認証情報が誤っているか、トークンの有効期限が切れている	Access Keys から Key ID を確認し、作成時に保存した Key Secret を使用してください。シークレットを紛失した場合は、新しい Access Key を作成して OAuth2 トークンを再取得してください。また、詳細を確認するため、レスポンスヘッダー WWW-Authenticate を調べてください（例：無効なトークン、期限切れのトークン、無効なクライアント）。
Voice／Verification で 401 Invalid Signature	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 が指定されていることを確認してください

リンク

以下のダッシュボードリンクへのアクセスには認証が必要です。人間のオペレーター向けであり、エージェントは手順に関するガイダンスには公開ドキュメントを利用し、ダッシュボードの URL はナビゲーション用の参照としてのみ扱ってください。

認証が必要なコンソールリンク（人間のオペレーター向け）：

• Sinch ダッシュボード：https://dashboard.sinch.com
• アクセスキー：https://dashboard.sinch.com/settings/access-keys
• 音声アプリ：https://dashboard.sinch.com/voice/apps
• 検証アプリ：https://dashboard.sinch.com/verification/apps
• Mailgun API キー：https://app.mailgun.com/settings/api_security

公開ドキュメントへのリンク（エージェント向け）：

• プロジェクト OAuth ドキュメント：https://developers.sinch.com/docs/numbers/api-reference/authentication/oauth
• 音声認証ドキュメント：https://developers.sinch.com/docs/voice/api-reference/authentication.md
• 検証認証ドキュメント：https://developers.sinch.com/docs/verification/api-reference/authentication.md
• Mailgun 認証ドキュメント：https://documentation.mailgun.com/docs/mailgun/api-reference/mg-auth.md
• アプリ内通話：https://developers.sinch.com/docs/in-app-calling/overview.md
• アクセスキーの作成方法：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