Bearer トークン
すべてのリクエストのAuthorization ヘッダーにキーを送信します：
Bearer プレフィックスがない、未知のキー、無効化されたキーの場合は、いずれも 401 invalid_api_key を受け取ります。
API キーの形式
すべてのキーはcdsk_ で始まり、その後に 45 文字のランダムな文字列が続きます（合計 50 文字）。本番／テストの区別はありません — すべてのキーはテナントの実データに対して動作します。
キーは 設定 → Open API → API キー で発行します。平文の値は作成時に一度だけ表示されます。Comdesk は SHA-256 ハッシュと、識別用の先頭 12 文字のみを保存します。
キーは個々のスタッフではなくテナントに属し、付与されたスコープの範囲内でテナントレベルで動作します。システムごとにキーを分けて発行すれば、いずれか 1 つを個別に失効できます。
ライセンス
すべての v1 エンドポイントは、テナントがopen_api ライセンスを保有している必要があります。Webhook とレポート API には、さらに open_api_advanced が必要です。必要なライセンスを持たないテナントは 403 license_required を受け取ります。
スコープ
キーには必要なスコープのみを付与します（最小権限）。キーのスコープ外のエンドポイントを呼ぶと403 insufficient_scope を受け取ります。
BI 連携には
reports:read のみ、リードインポートのジョブには customers:write のみで十分です。キーごとに最小限のスコープを付与してください。IP 許可リスト（任意）
各キーは、最大 10 個の送信元アドレスに制限できます。エントリには IPv4・IPv6 アドレス、または IPv4 の CIDR レンジ（例：203.0.113.0/24）を指定できます — IPv6 の CIDR レンジには対応していません。設定すると、それ以外の IP からのリクエストは 403 ip_not_allowed を受け取ります。無制限にする場合は空のままにします。
ブラウザのオリジン（CORS）
ブラウザから送信されるリクエストにはOrigin ヘッダーが付きます。クロスオリジンのリクエストは、テナント管理者が登録したオリジンからのみ受け付けられ、それ以外のオリジンは 403 origin_not_allowed を受け取ります。サーバー間のリクエスト（Origin ヘッダーなし）は影響を受けません。
キーの有効期限とローテーション
キーには任意で有効期限を設定して発行できます。期限を過ぎると、リクエストは401 expired_api_key を受け取ります。Comdesk はキーの有効期限の 30 日前にテナント管理者へメールで通知します。
キーは 6〜12 か月ごとにローテーションしてください：
1
新しいキーを作成する
同じスコープで新しいキーを発行します。古いキーはまだ無効化しません。
2
システムを更新する
連携の設定／シークレットストアのキーを差し替えます。
3
検証する
新しいキーでテストリクエストを 1 回送信し、
200 を確認します。4
古いキーを無効化する
検証後、API キー管理画面で古いキーを無効化します。
エラー
完全な一覧とエラーエンベロープは エラー を参照してください。