> 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-secrets.md).

# Project Secretを登録・更新・削除する

Project Secretは、Project単位でAPIキーやトークンなどの機密値を管理するための設定です。この記事では、**管理者が秘密情報を登録し、定期的に更新し、不要になった値を安全に削除する手順**を説明します。値は暗号化して保存され、一覧と編集画面では実値ではなくマスク表示になります。そのため、登録時の原文は安全な保管場所で管理し、この画面から後で読み出せる前提にはしません。

関連する内容は、[Appの初期設定を完了する](/u/complete-app-setup.md)、[Pageの仕様・制限](/shi-yang-zhi-xian/page-specs-and-limits.md)、[Pageのサーバー処理・環境変数・Secret参照](/gaidopage/page-server-env-and-secrets.md)、[Webログイン用シークレットを管理する](/guan-li-yun-yong/manage-web-login-secrets.md)を参照してください。Project SecretとWebログイン用シークレットは別の種類です。

## 始める前に

* 対象の組織・Project・利用中のAppを確認します。**組織でProject Secret機能が有効な場合にのみ**、設定画面を利用できます。項目が見つからない場合は、別画面やURLで代用せず、組織の管理担当者に確認してください。
* Project SecretはProject単位で管理します。同じ名前を同一Project内で重複登録できないため、既存の名前と用途を確認します。
* 操作には権限が必要です。閲覧にはSecretの「閲覧」、登録には「作成」、値の更新には「更新」、削除には「削除」の権限が必要です。登録・更新・削除は、これらに加えてProjectの編集可能な役割が必要です。画面を開けても、操作ごとの権限がなければ実行できない場合があります。
* 値を取得する外部サービス、用途、担当者、切替日時、戻し方を記録します。実値をチケット、チャット、説明欄、Pageの配布ファイル、ブラウザ用の設定、ログに書かないでください。

> Page/Appのリリース設定では、ルートの対象`.env`に`サーバー用の環境変数名=${secret:Secret名}`の形式で参照を宣言できます。実値を配布ファイルへ書くのではなく、対象ProjectのSecretを選択・紐づけて使います。`NEXT_PUBLIC_`、`VITE_`、`REACT_APP_`、`PUBLIC_`で始まるブラウザ公開用のキーには、この参照を指定できません。Page/Appの実行方式やサーバー側の実装は[Pageのサーバー処理・環境変数・Secret参照](/gaidopage/page-server-env-and-secrets.md)を確認してください。

## 入力規則と表示

| 項目    | ルール                                 | 例・注意点                                                              |
| ----- | ----------------------------------- | ------------------------------------------------------------------ |
| 名前    | 先頭は英小文字。以後は英小文字・数字・アンダースコアのみ。最大64文字 | `sales_api_token`。大文字、ハイフン、空白は使えません。空欄とUUID形式の名前も登録できません。          |
| 値     | 空欄にできず、最大8,192文字                    | 発行元から得た値をそのまま入力します。貼り付け前後の空白や改行が認証に影響しないか、発行元の説明で確認します。            |
| 一意性   | 同じProject内で名前は重複不可                  | 更新では名前を変更できません。名前を変える必要がある場合は、影響確認後に新しい名前で登録し、参照先を切り替えてから旧値を削除します。 |
| 一覧・詳細 | 値はマスク表示                             | 一覧には「名前」「値」「更新日時」「操作」が表示されます。編集を開いても現在値はマスクされるため、必要なら新しい値を再入力します。  |

> マスク表示は、値を失わないことや、利用中の処理が正常であることを保証しません。表示された文字列を実値としてコピーしたり、再登録したりしないでください。

## 1. 「プロジェクトシークレット」を開く

1. JAPAN AIで対象の組織とProjectを確認します。
2. Projectの設定から\*\*「プロジェクトシークレット」\*\*を開きます。
3. 一覧で名前、マスクされた値、\*\*「更新日時」**を確認します。必要に応じて、**「シークレット名で検索」\*\*で対象を絞り込みます。
4. 「プロジェクトシークレットを表示する権限がありません。」と表示される場合は、閲覧権限と対象Projectへのアクセスを確認します。

組織の設定や権限によって、画面の入口・表示内容・操作可否は異なります。Appの初期設定中に必要なSecretが示される場合は、Appの\*\*「アプリに必要なシークレット」\*\*で、必要な項目と現在の設定状況を確認します。

## 2. 新しい値を登録する

1. \*\*「シークレットを作成」**を選び、**「プロジェクトシークレットを作成」\*\*を開きます。
2. \*\*「名前」\*\*に、用途が分かる規則に従った名前を入力します。登録後、この画面から名前は変更できません。
3. \*\*「値」\*\*に、外部サービスから取得した実値を入力します。入力欄はパスワード形式で表示されます。
4. 入力規則、対象Project、発行元、担当者を再確認し、\*\*「作成」\*\*を選びます。
5. 「プロジェクトシークレットを作成しました」と表示されたら、一覧に名前と更新日時が表示され、値がマスクされていることを確認します。

Appに必要な項目として表示されている場合は、作成しただけでは設定完了とは限りません。画面にある\*\*「シークレットを選択」**で対象を選び、**「紐づけ」\*\*を実行し、状態を確認します。紐づけ方法やPageの実装方式を一般化せず、Appの案内と[Pageのサーバー処理・環境変数・Secret参照](/gaidopage/page-server-env-and-secrets.md)を確認してください。

## 3. 値を更新してローテーションする

値の漏えい疑い、発行元の失効予定、担当交代などでは、新しい値を発行して切り替えます。更新できるのは値であり、名前ではありません。

1. 対象の行の\*\*「操作」**から**「編集」**を選び、**「プロジェクトシークレットを編集」\*\*を開きます。
2. マスクされた既存値を消して、新しい実値を\*\*「値」\*\*へ入力します。値を変えない場合は、マスク表示のまま保存しないでください。
3. 対象名、発行元、切替時刻、影響するPage・App・Workflowを再確認し、\*\*「保存」\*\*を選びます。
4. 「プロジェクトシークレットを更新しました」と表示されたら、更新日時を確認します。
5. 実際の利用経路で、認証を要する代表操作をテストします。PageやWorkflowが参照している可能性がある場合は、利用者へ切替完了を案内する前に、対象ごとに成功・失敗を確認します。

更新後に既存のPageやWorkflowへいつ反映されるか、再公開・再実行が必要か、処理中の実行にどう影響するかは、この確認範囲では確定できません。直ちに反映される、無停止で切り替わる、と断定しないでください。

### ローテーション・チェックリスト

* [ ] 新しい値が発行元で有効であることを確認した
* [ ] 対象、Secret名、担当者を確認した
* [ ] 新しい値を登録または更新した
* [ ] 影響する代表操作をテストした
* [ ] 旧値を失効する前に切替完了を確認した
* [ ] 実値を記録・共有していないことを確認した

## 4. 不要な値を削除する

削除は復元できません。名前を変えたい、またはローテーション中の場合も、先に新しい値の登録・紐づけ・テストを終え、旧値の利用がなくなってから削除します。

1. 一覧で対象の名前と更新日時を確認します。
2. \*\*「操作」**から**「削除」\*\*を選びます。
3. \*\*「プロジェクトシークレットを削除」\*\*の確認内容を読みます。Appから参照されている場合は、参照されている項目も確認します。
4. 依存するPage・App・Workflowの担当者へ連絡し、代替値の設定とテストが完了していることを確認します。
5. \*\*「削除」\*\*を確定します。「プロジェクトシークレットを削除しました」と表示され、一覧から対象が消えたことを確認します。

> Appから参照されているSecretを削除しても、App自体は利用できる場合があります。一方で、依存する一部の機能は実行時エラーになる可能性があります。削除前に表示される参照項目を確認し、利用中のPage・App・Workflowをテストしてください。Page側の具体的な参照方式は未確認のため、本記事では説明しません。

## うまくいかない場合

| 状況                        | 確認・対応                                                                         |
| ------------------------- | ----------------------------------------------------------------------------- |
| 「プロジェクトシークレット」が見つからない     | 組織で機能が有効か、対象の組織・Projectか、権限があるかを管理担当者へ確認します。別のSecret種別で代用しません。                |
| 作成・編集・削除が選べない             | Secretの操作別権限と、Projectを編集できる役割を確認します。必要以上の権限を自分で付与せず、権限管理者へ依頼します。              |
| 名前または値で保存できない             | 名前が64文字以内で規則に合うか、値が空でなく8,192文字以下か、同名が既にないかを確認します。実値は問い合わせに貼り付けません。            |
| 一覧・詳細で値を確認できない            | これはマスク表示の仕様です。発行元または安全な保管場所で実値を確認し、必要なら新しい値として更新します。                          |
| 更新・削除後にPageやWorkflowが失敗する | 変更対象、実行時刻、表示されたエラー、影響する操作を記録します。推測で再公開・再実行・権限変更を繰り返さず、直前の切替状況と参照設定を担当者と確認します。 |

問い合わせには、組織名、Project名、Secret名、操作種別、日時、表示メッセージ、影響したPage・App・Workflow、実施済みの確認を添えます。値、APIキー、トークン、パスワード、画面のマスク文字列は添付しないでください。

## 次に読む記事

* [Appの初期設定を完了する](/u/complete-app-setup.md)
* [Pageの仕様・制限](/shi-yang-zhi-xian/page-specs-and-limits.md)
* [Pageのサーバー処理・環境変数・Secret参照](/gaidopage/page-server-env-and-secrets.md)
* [Webログイン用シークレットを管理する](/guan-li-yun-yong/manage-web-login-secrets.md)
