> For the complete documentation index, see [llms.txt](https://studio-docs.japan-ai.co.jp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://studio-docs.japan-ai.co.jp/guan-li-yun-yong/manage-project-api-keys.md).

# Project APIキーを管理する

Project APIキーは、外部システムや開発時のプログラムから、対象Projectのリソースへアクセスするための認証情報です。この記事では、管理者・開発者がキーを発行し、用途に応じたスコープ（権限）と有効期限を選び、更新時には安全に切り替え、不要・漏えいしたキーを失効させる手順を説明します。

実行モードごとの認証方法や、コードへ渡す方法は[実行モード・認証・対応範囲](/gaidobito/execution-modes-and-auth.md)を参照してください。メンバー情報を取得するAPIの利用条件は[Project Members API](/apirifarensu/project-members-api.md)、SDK／APIのエラーの切り分けは[SDK／APIのエラーを切り分ける](/toraburushtingu/isolate-sdk-api-errors.md)で扱います。

## 始める前に

* 対象の組織・Project・外部システムを確認します。キーはProjectごとに発行されるため、開発・検証・本番に相当するProjectを取り違えないでください。
* APIキー管理が利用可能な組織・Projectであることを確認します。項目が表示されない場合、別の認証情報で代用したり、画面のURLを推測したりせず、組織の管理担当者へ確認します。
* キーを作成する人、利用するシステム、保管責任者、停止判断をする人を決めます。キーを発行した人がProjectの利用条件を満たさなくなると、そのキーも利用できなくなる場合があります。
* 必要な操作を先に洗い出します。スコープは、読み取り・書き込み・削除・実行などの対象ごとに選びます。利用予定のないスコープや「すべてのスコープを選択」は選ばないでください。

> Project APIキーはProject Secretとは別のものです。外部サービスから受け取った秘密値をProject内で保管する用途は、[Project Secretを登録・更新・削除する](/guan-li-yun-yong/manage-project-secrets.md)を参照してください。APIキーそのものをブラウザのソース、公開リポジトリ、チャット、チケット、ログへ書き込んではいけません。

## 管理できる人と確認できる情報

キーの一覧には、名前、マスクされたキー、スコープ、有効期限、最終使用、作成者、操作が表示されます。実値を一覧から再表示することはできません。

| 操作        | 必要な条件の目安                        | 注意点                                                                               |
| --------- | ------------------------------- | --------------------------------------------------------------------------------- |
| 一覧を確認する   | 対象Projectを閲覧でき、キー情報を閲覧する権限があること | 実値ではなくマスク表示です。                                                                    |
| 新規に発行する   | 対象Projectを編集でき、キーを作成する権限があること   | Projectの管理者または編集者であっても、追加の権限設定により実行できない場合があります。                                   |
| 削除して失効させる | 対象のキーを削除する権限があること               | 管理者は他の人が作成したキーも扱える場合があります。編集者は自分が作成したキーだけを削除できる場合があります。個別の権限設定がある場合は、その設定が優先されます。 |

画面を開けても、作成・削除を実行できるとは限りません。操作が無効な場合は必要以上の権限を自分で付与せず、Projectの管理担当者へ依頼してください。

## 1. 「APIキー管理」を開く

1. JAPAN AIで正しい組織と対象Projectを開きます。
2. Projectの設定から\*\*「APIキー管理」\*\*を開きます。
3. 一覧で既存キーの名前、スコープ、**「有効期限」**、**「最終使用」**、作成者を確認します。まず既存キーを利用できないか、同じ外部システム用のキーが残っていないかを確認してください。
4. 「APIキー管理はこのプロジェクトで有効になっていません。」と表示される場合は、組織の管理担当者へ利用可否を確認します。

一覧の「未使用」は、利用できることを示すものではありません。また、最終使用は確認の補助情報です。停止の判断をこれだけに依存せず、利用システムの設定、担当者、実行記録も確認します。

## 2. 新しいAPIキーを発行する

1. \*\*「APIキーを作成」\*\*を選びます。
2. \*\*「名前」\*\*に、用途・接続先・担当を識別できる名前を入力します。例：`受注連携_検証用`。キーの実値、パスワード、個人情報は名前に含めません。
3. \*\*「スコープ（権限）」\*\*で、必要な対象と操作だけを選びます。少なくとも1つのスコープが必要です。
4. **「有効期限」で、利用期間に合う期限を選びます。選択肢は「7日間」**、**「30日間」**、**「90日間」**、\*\*「365日間」\*\*です。短期の検証には短い期限を選び、期限前に切替日を予定します。
5. 対象Project、名前、スコープ、有効期限、保管先を確認して\*\*「作成」\*\*を選びます。
6. 「APIキーが作成されました」と表示されたら、実値をコピーし、組織で承認された秘密情報の保管場所へ直ちに保存します。保管できたことを確認してから\*\*「完了」\*\*を選びます。

> 実値は**作成時に一度だけ**表示されます。閉じた後に確認できるのはマスク表示です。実値を失った場合に既存キーを復元・表示するのではなく、影響を確認して新しいキーを発行し、利用システムを切り替えてください。

### スコープを選ぶ考え方

画面では、オントロジー、Storage、Dataset、Object、Page、Agent、Workflow、**タスクスケジューラー**、メンバー、**クレジット利用量**、LLMのスコープが表示される場合があります。各対象には、読み取り・書き込み・削除・実行などのスコープがあります。表示される対象やスコープは組織の利用条件によって異なる場合があります。

#### `credit:read`を選ぶ場合

`credit:read`は、組織でクレジット利用量の閲覧機能が有効であり、キーを作成する人が**組織またはProjectの管理者**である場合にだけ選べます。このスコープを含むキーには、ほかの`:read`スコープだけを併用できます。書き込み、削除、実行などのスコープは同じキーに追加できません。

\*\*「すべてのスコープを選択」\*\*では`credit:read`は選択されません。クレジット利用量の参照が必要な場合も、利用目的に合う読み取りスコープだけを個別に選び、キーの作成時に画面の検証結果を確認してください。

| 利用目的                | 選ぶスコープの考え方                                                                                                                                                                   |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ファイルを参照する           | Storageの読み取りだけを選びます。アップロードや削除が不要なら追加しません。                                                                                                                                    |
| データやObjectを更新する     | 対象の書き込みを選びます。削除は運用上必要な場合だけを追加します。                                                                                                                                            |
| Agent・Workflowを利用する | 読み取りが必要か、実行だけでよいかを分けて選びます。Workflowの変更・削除は運用担当を限定します。                                                                                                                         |
| SDK／APIから定期タスクを管理する | 一覧には`task:read`、作成・更新には`task:write`と`workflow:execute`、削除には`task:delete`を選びます。                                                                                               |
| メンバー情報やLLMを利用する     | 必要なAPI・実行モード・組織の利用条件を[実行モード・認証・対応範囲](/gaidobito/execution-modes-and-auth.md)、[Project Members API](/apirifarensu/project-members-api.md)で確認してから選びます。画面に表示されないスコープを前提に実装しません。 |

> 「書き込み」があっても「削除」が必要とは限りません。まず最小限で接続テストを行い、権限不足が分かったときだけ、必要な範囲を確認して新しいキーを発行します。作成済みキーのスコープや期限を後から変更する手順は、この画面では確認できません。

### SDK／CLIで定期タスクを扱う場合

Studio SDK／CLIの定期タスク機能は、Project APIキーで利用します。タスクは**キーの作成者として実行**され、作成者が操作時点で持たない権限をキーで補うことはできません。また、対象にできるのはそのProjectで作成したWorkflowです。組織から取り込んだWorkflowは定期タスクにできません。

作成後に変更できるのは送信した項目です。Workflowと所有者は変更できないため、担当変更や実行対象の変更では、新しいキー・タスクの作成、動作確認、旧タスクの停止・削除を順に行います。Appのリリースマニフェストには`task:*`スコープを含められないため、Appのサーバー実行環境でこの機能を使える前提にしません。SDK／CLIの具体的な呼び出しは、利用中のSDKバージョンのリファレンスを確認してください。

## 3. 利用開始前に確認する

1. 承認された保管場所からキーを利用システムの安全な設定へ登録します。画面やログに実値を表示しない設定を確認します。
2. 許可された検証用のProject・データ・アカウントを使い、必要な代表操作だけを実行します。
3. 意図した操作だけが成功し、不要な読み取り・書き込み・削除ができないことを確認します。
4. 「APIキー管理」の一覧へ戻り、名前、スコープ、有効期限、作成者を記録します。実値は記録しません。
5. 利用システム、保管責任者、更新予定日、失効時の連絡先を台帳に記録します。

SDKまたはAPIの具体的なヘッダー、設定ファイル、実行環境への渡し方は本記事の範囲外です。キーをクライアント側のコードへ埋め込まず、[実行モード・認証・対応範囲](/gaidobito/execution-modes-and-auth.md)の認証方式に従って設定してください。

## 4. 更新（ローテーション）する

キーの値、スコープ、有効期限を編集して更新する操作は確認できません。期限切れが近い場合、担当変更、用途変更、または漏えいの疑いがある場合は、次の順で新しいキーへ切り替えます。

1. 影響する外部システム、実行処理、現在のキー名、担当者、切替日時を確認します。
2. 新しい用途・最小スコープ・新しい有効期限で、手順2により新しいキーを発行します。
3. 新しいキーを安全な設定へ登録し、代表操作をテストします。失敗したときの連絡先と旧キーを停止する判断を事前に決めます。
4. 利用システムが新しいキーだけで動作することを確認します。
5. 旧キーを失効させます。並行利用の期間を必要最小限にし、切替完了後に放置しないでください。

## 5. 不要・漏えいしたキーを失効させる

削除は取り消せません。削除すると、そのキーを使用するシステムはアクセスできなくなります。不要なキー、担当外になったキー、漏えいの疑いがあるキーは、利用状況を確認して削除します。漏えいが疑われる場合は、先に新しいキーを発行して切り替え、調査よりも失効を優先してください。

1. 一覧で対象の名前、スコープ、有効期限、最終使用、作成者を確認します。
2. 対象行の\*\*「削除」\*\*を選びます。
3. \*\*「APIキーを削除」\*\*の確認内容と対象名を確認します。
4. 利用システムの切替または停止が完了していることを確認して、\*\*「削除」\*\*を確定します。
5. 「APIキーを削除しました」と表示され、一覧から対象が消えたことを確認します。

## うまくいかない場合

| 状況                               | 確認・対応                                                                                                                                       |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| 「APIキー管理」が表示されない、または有効ではないと表示される | 対象の組織・Project、利用条件、権限を確認し、組織の管理担当者へ問い合わせます。                                                                                                 |
| 「APIキーを作成」が選べない                  | Projectを編集できるか、キーを作成する権限があるかを確認します。                                                                                                         |
| 削除が選べない                          | 対象キーの削除権限、作成者、自分のProject上の役割を確認します。必要なら管理者へ依頼します。                                                                                           |
| 作成後に実値を控え忘れた                     | 一覧のマスク表示から復元しようとせず、新しいキーを発行して利用システムを切り替えます。旧キーは切替確認後に削除します。                                                                                 |
| API・SDKで認証や権限エラーになる              | 対象Project、キーの有効期限、削除・失効の有無、必要なスコープ、実行モード、キーの設定先を順に確認します。実値は問い合わせに送らず、[SDK／APIのエラーを切り分ける](/toraburushtingu/isolate-sdk-api-errors.md)を参照します。 |

## チェックリスト

* [ ] 対象の組織・Project・利用システムを確認した
* [ ] 管理する人、保管責任者、失効時の連絡先を決めた
* [ ] 必要最小限のスコープと有効期限を選んだ
* [ ] 実値を作成時に安全な保管場所へ保存し、コードやログへ残していない
* [ ] 代表操作と、不要な操作ができないことを確認した
* [ ] 更新時は新しいキーのテスト後に旧キーを削除する計画にした
* [ ] 不要・漏えい疑い・担当外のキーを速やかに失効させた

## 関連記事・次に読む記事

* [実行モード・認証・対応範囲](/gaidobito/execution-modes-and-auth.md)
* [Project Members API](/apirifarensu/project-members-api.md)
* [SDK／APIのエラーを切り分ける](/toraburushtingu/isolate-sdk-api-errors.md)
* [Project Secretを登録・更新・削除する](/guan-li-yun-yong/manage-project-secrets.md)
