認証 - Comdesk ヘルプ

Comdesk Open API は、すべてのリクエストを Bearer トークンとして送信される API キーで認証します。各キーは、何ができるかを定める一連のスコープを持ち、任意で利用元を制限する IP 許可リストを持ちます。

Bearer トークン

すべてのリクエストの Authorization ヘッダーにキーを送信します：

Authorization: Bearer cdsk_live_xxxxxxxxxxxxxxxxxxxx

有効なキーがないリクエストは 401 invalid_api_key を受け取ります。

プレフィックス	環境	動作
`cdsk_live_…`	本番	実運用 — 実際の発信、実データの書き込み
`cdsk_test_…`	サンドボックス	安全なテスト — 実際の発信なし、緩めのレート制限

キーは 設定 → Open API → API キー で発行します。平文の値は作成時に一度だけ表示されます。Comdesk は SHA-256 ハッシュと検索用の短いプレフィックスのみを保存します。

キーを紛失すると復元できません。新しいキーを作成してローテーションしてください。キーをソース管理にコミットしたり、クライアント側コードに露出させたりしないでください。

種類	発行者	権限レベル
テナントキー	管理者	組織全体に対し管理者レベルで動作
スタッフキー	スタッフ個人	そのスタッフ自身の権限に限定

システム間連携（CRM、BI）にはテナントキーを、特定ユーザーとしてのみ動作させたい場合はスタッフキーを使います。

キーには必要なスコープのみを付与します（最小権限）。キーのスコープ外のエンドポイントを呼ぶと 403 insufficient_scope を受け取ります。

キーごとに最小限のスコープを付与してください。Salesforce のクリック発信用キーには calls:initiate のみで十分で、reports:read は不要です。システムごとにキーを分けて発行すれば、いずれか 1 つを個別に失効できます。

各キーは、送信元 IP または CIDR レンジ（例：203.0.113.0/24）に制限できます。設定すると、それ以外の IP からのリクエストは 403 ip_not_allowed を受け取ります。無制限にする場合は空のままにします。

キーは 6〜12 か月ごとにローテーションしてください。Comdesk はキーの有効期限の 30 日前にテナント管理者へメールで通知します。

新しいキーを作成する

同じスコープで新しいキーを発行します。古いキーはまだ無効化しません。

システムを更新する

連携の設定／シークレットストアのキーを差し替えます。

検証する

新しいキーでテストリクエストを 1 回送信し、200 を確認します。

古いキーを無効化する

検証後、API キー管理画面で古いキーを無効化します。無効化は約 5 分で反映されます。

完全な一覧とエラーエンベロープはエラーを参照してください。