APIキー
個人またはサービスの権限を選び、シークレットを作成時に保存。呼び出し元を見失うことなく、認証情報を置き換えられます。
APIキーを使うと、呼び出し元は定められた権限で操作できます。個人キーの権限は、その人の組織への所属状況と権限に連動します。組織のサービスキーは組織に属するため、特定のメンバーが離れても、その人に依存せず自動処理を継続できます。ロールベースのアクセス制御を使えば、サービスキーに独自のロールとリソーススコープを設定することもできます。
シークレットが表示されるのは作成時だけです。後からキーの記録を確認しても復元できません。シークレット管理ツール、または呼び出し元が対応する認証情報ストアに、すぐに保存してください。ソースファイル、コミットする設定ファイル、スクリーンショット、サポートへのメッセージには含めないでください。
個人として行う作業には個人キーを使う #
選択した組織の設定 → APIキー → 個人で、個人キーを作成し、名前を付けます。メンバーは自分用のキーを作成できます。キーの権限は、作成者の現在の所属状況と実効権限に連動します。サービスキーとは異なり、個別のロールやローカライゼーションエンジンごとのスコープは設定できません。
個人キーは、ローカル環境の呼び出し元を操作者本人の権限で動かす場合に便利です。メンバーが組織を離れたり権限を失ったりすると、キーのアクセス権も変わります。組織の自動処理を、その人がアクセス権を持ち続けることに依存させたくない場合は、サービスキーを使ってください。
サービスキーを作成する #
選択した組織の設定 → APIキー → 組織で、新しい組織キーを選択します。サービスキーはすべてのプランで利用できます。作成にはorg:manage_api_keysが必要です。
ロールベースのアクセス制御を使わない場合、サービスキーのアクセス範囲は絞り込めず、組織内のすべてのローカライゼーションエンジンで読み取りと翻訳が可能になります。作成フォームには、ロールとエンジンの入力欄の代わりに注意書きが表示されます。
この基本的なアクセス権では、ローカライゼーションエンジンの編集や削除、翻訳のレビュー、組織の管理はできません。
ロールベースのアクセス制御を使う場合は、キーにロール、ローカライゼーションエンジンのスコープ、またはその両方を設定し、後から編集できます。呼び出し元には、選択したロールを委任する権限と、スコープ内のすべてのローカライゼーションエンジンで翻訳する権限が必要です。読み取り権限だけでは、翻訳スコープを付与できません。
サービス用ロールとして許可されるのは、engine:readとengine:translateです。ロールはその組織に属している必要があり、より広範な管理権限を含めることはできません。サービスキーにロールを設定せず、明示的に付与したリソース権限だけで運用することもできます。
ローカライゼーションエンジンのスコープとコンテンツリソースのスコープは別々に設定し、保存後に各フィールドを読み取って確認してください。一方の権限更新が成功しても、もう一方が失敗する場合があります。ロールによる権限と明示的に付与した権限は、足し合わせて適用されます。スコープを狭めても、ロールによる広範なアクセス権は取り消されません。ロールベースのアクセス制御を使う場合、適切なロールもリソース権限もないキーは、作成しただけでは実用的な翻訳権限を持ちません。
キーの作成とスコープの編集には、キー管理画面を使ってください。この一連の管理手順を自動化する場合は、どのクライアントでも対応していると考えず、使用するクライアントが必要な管理操作に対応しているか確認してください。
ロールベースのアクセス制御を無効にする前に
ロールベースのアクセス制御を無効にすると、通常のサービスキーは、組織全体で読み取りと翻訳ができる状態に戻ります。保存済みのロールやエンジンの制限は、アクセス範囲に適用されなくなります。これらの制限が必要な場合は、ロールベースのアクセス制御を無効にする前に、キーを失効させるかローテーションしてください。SCIMキーなど、特定の用途向けの認証情報には、別のアクセス要件があります。
認証情報をローテーションする、または失効させる #
ローテーションでは、次の手順でキーを手動で置き換えます。
- 使用するキーの種類と必要最小限の権限を指定して、置き換え用のキーを作成します。
- 呼び出し元のシークレット管理の仕組みに、新しいキーのシークレットを保存します。
- キーに依存する呼び出し元を更新し、それぞれが対応するインターフェースを通じて、想定する小規模な操作ができることを確認します。
- 確認後、古いキーを失効させます。漏えいへの対応で直ちに被害を封じ込める必要がある場合は、先に失効させ、それに伴う中断にも対処してください。
- 現在のキーの記録と呼び出し元のエラー状況を調べ、見落とした依存関係がないか確認します。
キーの記録にアクセスできる組織メンバーは、通常の個人キーやサービスキーを失効させることができます。この失効権限は、サービスキーの作成やスコープの編集に必要な権限よりも、広い範囲のメンバーに認められています。SCIMキーを失効させるには、組織のオーナーである必要があります。削除についてやり取りする際は、シークレットではなくキーの識別子を使ってください。
キーを失効させても、他の場所に保存されたコピーは消去されず、ブラウザのセッションも失効しません。この一連の管理手順は、自動ローテーションや有効期限のスケジュールが設定されていることを意味するものではありません。
実際の呼び出し元を設定する #
RESTリクエストでは、選択したAPIのX-API-Keyヘッダーを使います。401は認証の問題を、403は権限による拒否を示します。前者では認証情報を、後者では認証主体の権限とリソーススコープを確認してください。その場で組み立てたURLに認証情報を含めないでください。
呼び出し元の通信方法や認証情報の保存方法については、API認証、CLI認証、またはMCP接続仕様を参照してください。選択するローカライゼーションエンジンは、その呼び出し元の権限の範囲内である必要があります。