> ## Documentation Index
> Fetch the complete documentation index at: https://help.comdesk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 認証

> API キーによる認証、スコープ、キーの種類、IP 許可リストを理解します。

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

## Bearer トークン

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

```text theme={null}
Authorization: Bearer cdsk_live_xxxxxxxxxxxxxxxxxxxx
```

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

## API キーの形式

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

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

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

## キーの種類

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

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

## スコープ

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

| スコープ                  | 付与する権限        | 用途                |
| --------------------- | ------------- | ----------------- |
| `calls:initiate`      | 発信の開始         | クリックして発信、IVR トリガー |
| `calls:read`          | 通話履歴の読み取り     | 履歴同期、レポート         |
| `calls:write`         | 通話履歴の作成・更新    | 履歴の書き戻し           |
| `customers:read`      | 顧客データの読み取り    | 顧客同期              |
| `customers:write`     | 顧客の作成・更新      | リードインポート          |
| `reports:read`        | 統計の読み取り       | BI 連携             |
| `webhooks:manage`     | Webhook 設定の管理 | Webhook セットアップ    |
| `integrations:manage` | 連携トリガーの管理     | 連携の自動化            |

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

## IP 許可リスト（任意）

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

## キーのローテーション

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

<Steps>
  <Step title="新しいキーを作成する">
    同じスコープで新しいキーを発行します。古いキーはまだ無効化しません。
  </Step>

  <Step title="システムを更新する">
    連携の設定／シークレットストアのキーを差し替えます。
  </Step>

  <Step title="検証する">
    新しいキーでテストリクエストを 1 回送信し、`200` を確認します。
  </Step>

  <Step title="古いキーを無効化する">
    検証後、API キー管理画面で古いキーを無効化します。無効化は約 5 分で反映されます。
  </Step>
</Steps>

## エラー

| ステータス | コード                  | 原因               |
| ----- | -------------------- | ---------------- |
| 401   | `invalid_api_key`    | キーが欠落・不正・失効      |
| 401   | `expired_api_key`    | キーが有効期限切れ        |
| 403   | `insufficient_scope` | キーに必要なスコープがない    |
| 403   | `ip_not_allowed`     | 送信元 IP が許可リストにない |

完全な一覧とエラーエンベロープは [エラー](/developer/open-api/file-3) を参照してください。