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

# APIキー

> CaseBender APIキーを作成し、スコープ設定、監視、ローテーション、一時停止、失効、安全な利用を管理します。

## 概要

APIキーを使用すると、プログラムからCaseBenderにアクセスできます。自分のアカウントと現在の組織で利用可能なキーを管理するには、**設定 → アカウント → APIキー**を開きます。

このページでは、次の機能を利用できます。

* 検索およびステータスまたは階層による絞り込み
* マスクされたキー識別子
* ステータス、階層、最終使用日時、リクエスト数
* 使用状況の統計
* ローテーション、一時停止、失効、削除などのライフサイクル操作

<Warning>
  APIキーは認証情報です。承認済みのシークレットマネージャーに保存し、ソース管理には決してコミットしないでください。また、ログ、スクリーンショット、チケット、チャットメッセージに含めないでください。
</Warning>

## 前提条件

* ロールで書き込み操作とAPIキー管理が許可されている必要があります。
* 利用できるスコープはロールに応じて絞り込まれます。
* キーの作成、失効、削除には、ステップアップ認証が必要な場合があります。
* 組織で追加の認証ポリシーとアクセスポリシーが適用される場合があります。

読み取り専用ロールは許可された情報を表示できますが、キーを変更することはできません。

## APIキーを作成する

<Steps>
  <Step title="APIキーを開く">
    **設定 → アカウント → APIキー**に移動します。
  </Step>

  <Step title="作成を開始する">
    **APIキーを作成**を選択します。
  </Step>

  <Step title="キーを説明する">
    ワークロード、所有者、目的を識別できる明確な**名前**と、任意の説明を入力します。
  </Step>

  <Step title="階層を選択する">
    ワークロードで想定されるリクエスト量に適した階層を選択します。利用可能な階層は**Basic**から**Unlimited**までです。
  </Step>

  <Step title="有効期限を設定する">
    必要に応じて、有効期限までの日数を入力します。本番環境の認証情報には、ポリシーに準拠した短い有効期間を推奨します。
  </Step>

  <Step title="スコープを選択する">
    1つ以上のスコープを選択します。ワークロードがロールで利用可能なすべてのスコープを正当に必要とする場合にのみ、**すべて選択**を使用してください。
  </Step>

  <Step title="作成して認証する">
    **キーを作成**を選択し、求められた場合はステップアップ認証を完了します。
  </Step>

  <Step title="認証情報を保存する">
    **APIキーを保存**に表示された完全なキーを承認済みのシークレットマネージャーにコピーしてから、**完了**を選択します。
  </Step>
</Steps>

<Warning>
  完全なキーが表示されるのは一度だけです。CaseBenderが保存するのは、キーの検証と識別に必要な情報だけです。平文の認証情報を後から取得することはできません。
</Warning>

## スコープを選択する

スコープでは、`cases:read`や`organizations:*`のようなリソースとアクションのパターンを使用します。スコープのカテゴリには、ケース、アラート、タスク、ユーザー、チーム、組織、設定、APIキー管理などがあります。

最小権限の原則に従ってください。

* レポート作成と検索のワークロードには、読み取り専用スコープを使用します。
* 統合で変更操作を実行する場合にのみ、書き込みスコープを付与します。
* 単一目的の統合では、ワイルドカードスコープと管理スコープを避けます。
* 関係のないサービスや環境には、別々のキーを作成します。
* 統合を変更するたびに、必要なスコープを確認します。

設定の作成フォームには、現在のロールで許可されているスコープだけが表示されます。APIリクエストは、キーのスコープと、強制適用されるその他のデータ制御に基づいて評価されます。

<Warning>
  `api-keys:write`、ワイルドカード、管理スコープは、他の認証情報を作成または管理することを明示的に認可された、信頼できる自動化にのみ付与してください。
</Warning>

## 階層を選択する

階層は、キーに意図されたサービスクラスを記録します。利用可能な階層は次のとおりです。

* **Basic**
* **Standard**
* **Professional**
* **Enterprise**
* **Unlimited**

実際のリクエスト、バルク操作、同時実行数の制限は、デプロイ構成によって異なります。階層を選択することで有効な制限が変わったり、キーが無制限になったりすると想定せず、本番環境のスループットと制限の適用についてプラットフォーム管理者に確認してください。

## APIリクエストを認証する

対応している単一キー用ヘッダーのいずれかで、完全なキーを使用します。

### 推奨：Bearerトークン

```bash theme={null}
curl "https://your-instance.casebender.com/api/v1/alerts" \
  --header "Authorization: Bearer $CASEBENDER_API_KEY" \
  --header "Content-Type: application/json"
```

### 代替：X-Api-Key

```bash theme={null}
curl "https://your-instance.casebender.com/api/v1/alerts" \
  --header "X-Api-Key: $CASEBENDER_API_KEY" \
  --header "Content-Type: application/json"
```

<Note>
  キーは環境変数またはシークレット注入機構に保存してください。実際のキーをシェル履歴やソースコードに直接貼り付けないでください。
</Note>

その他の例については、[APIリファレンスの概要](/ja/api-reference/introduction)を参照してください。

## キーのステータスを理解する

* **Active**のキーは、スコープとポリシーのチェックを条件としてリクエストを認証できます。
* **Suspended**のキーは一時的に無効で、再度有効にできます。
* **Revoked**のキーは永久に無効です。
* **Expired**のキーは、設定された有効期限を過ぎています。

## 使用状況の統計を表示する

キーのアクションメニューを開き、**統計を表示**を選択すると、次の項目を確認できます。

* リクエスト総数
* 成功したリクエスト数
* 失敗したリクエスト数
* 平均応答時間
* 上位のエンドポイント

これらの統計を使用して、未使用の認証情報、想定外のエンドポイント、別の階層が必要なワークロードを特定します。

## キーをローテーションする

ローテーションでは、現在のシークレットを新しいものに置き換えます。

<Steps>
  <Step title="利用側を準備する">
    キーを使用するサービスをすぐに更新でき、ロールバック計画があることを確認します。
  </Step>

  <Step title="ローテーションする">
    キーのアクションメニューを開き、**キーをローテーション**を選択します。
  </Step>

  <Step title="新しいキーを保存する">
    新しく表示された認証情報をシークレットマネージャーにコピーします。
  </Step>

  <Step title="更新して検証する">
    キーを使用するワークロードを更新し、必要に応じて再起動または再デプロイして、スコープ内のテストリクエストを送信します。
  </Step>
</Steps>

<Warning>
  ローテーションすると、以前のシークレットは無効になります。統合の停止を避けるため、変更を調整して実施してください。
</Warning>

ローテーションはオペレーターが開始します。ローテーション間隔を保存しただけでは、CaseBenderが置換キーを自動的にローテーションして配布することは保証されません。

## キーを一時停止または再有効化する

調査または計画メンテナンス中にキーを一時的に停止するには、**一時停止**を使用します。認証情報とその利用側が信頼できることを確認した後にのみ、**再有効化**を使用してください。

元に戻せる封じ込め操作が必要な場合は、削除よりも一時停止が適しています。

## キーを失効させる

認証情報が侵害された、信頼できなくなった、または永久に廃止する場合は、**失効**を使用します。失効にはステップアップ認証が必要な場合があり、元に戻すことはできません。

失効後は、次を実施します。

1. すべての利用側からシークレットを削除します。
2. 使用状況の統計とセキュリティテレメトリーを確認します。
3. 想定外のリクエストを調査します。
4. ワークロードが引き続き認可されている場合にのみ、別の置換キーを作成します。

## キーを削除する

削除すると、キーレコードと直接の管理表示がなくなります。ステップアップ認証が必要な場合があります。

<Warning>
  認証情報の廃止手順を明確にする必要がある場合は、キーを削除する前に失効させてください。現在のアクションメニューでは、すべての破壊的操作に個別の確認ダイアログが表示されるわけではありません。
</Warning>

## セキュリティに関する推奨事項

* 指名された担当者とワークロード所有者を割り当てます。
* 本番、ステージング、開発には別々のキーを使用します。
* 認証情報ポリシーに沿った有効期限を設定します。
* 漏えいが疑われる場合は直ちにローテーションします。
* 失敗したリクエストと想定外のエンドポイントを監視します。
* 未使用のキーを有効なまま残さず、失効させます。
* メールやコラボレーションツールでキーを送信しないでください。

## トラブルシューティング

### キーの作成が拒否される

名前を入力し、1つ以上のスコープを選択して、ロールに書き込みアクセス権があることを確認し、ステップアップ認証の要求があれば完了してください。

### APIリクエストで401が返される

完全かつ有効なキーがBearerトークンまたは`X-Api-Key`として指定されていることを確認し、有効期限切れ、一時停止、失効のいずれにも該当しないことを確認してください。

### APIリクエストで403が返される

キーの認証には成功しましたが、必要なスコープまたはデータアクセス権がありません。認可されたキー管理ワークフローを通じて、最低限必要なスコープだけを追加してください。

### リクエストがレート制限される

リクエスト頻度を下げ、レスポンスの再試行ガイダンスに従うか、ワークロードに別の階層が必要かどうかを管理者に確認してください。

### 完全なキーが表示されなくなった

平文のキーは取得できません。キーをローテーションするか置換キーを作成し、利用側を更新してください。

## APIリファレンス

* [APIキーの一覧を取得](/en/api-reference/endpoint/api-keys/list)
* [APIキーを作成](/en/api-reference/endpoint/api-keys/create)
* [利用可能なスコープの一覧を取得](/en/api-reference/endpoint/api-keys/scopes)
* [APIキーを取得](/en/api-reference/endpoint/api-keys/get-by-id)
* [APIキーをローテーション](/en/api-reference/endpoint/api-keys/rotate)
* [APIキーの統計を表示](/en/api-reference/endpoint/api-keys/stats)
* [APIキーを削除](/en/api-reference/endpoint/api-keys/delete)

## 関連ガイド

* [APIリファレンスの概要](/ja/api-reference/introduction)
* [アクセス制御](/en/security/access-control)
* [組織](./organizations.mdx)