アプリの非公開認証情報は Atoms クラウド → キー に保存して、その値が Chat やソースコードに含まれないようにし、Test 用と Production 用で別々の値を管理します。

キー を使用する前に、プロジェクトを Atoms クラウド に接続してください。接続されていない場合は、エージェントに Atoms クラウド の接続を依頼するか、Atoms クラウド を参照してください。

Atoms クラウド でキーを使う

始める前に

キーを追加する前に、次を確認してください。

• Atoms をデスクトップ Web で使用していること。
• プロジェクトが Atoms クラウド に接続されていること。
• あなたがワークスペースのオーナーであること。新しいキーを追加できるのはワークスペースのオーナーのみです。

キー または New Key が利用できない場合は、意図したプロジェクトを開いていること、およびそのプロジェクトが Atoms クラウド に接続されていることを確認してください。 New Key が引き続き利用できない場合は、あなたがワークスペースのオーナーであることを確認してください。Atoms にプランまたは利用可否に関するメッセージが表示される場合は、画面上の案内に従って利用可能にするかアップグレードしてから、再度お試しください。

Test キーを追加する

1. デスクトップ端末でプロジェクトを開きます。
2. App ビューアー がある同じワークスペースのツールバーで、Atoms クラウド を選択します。
3. Atoms クラウド のサイドバーで キー を選択します。
4. Test Keys を開き、次に In This Project を選択します。
5. New Key を選択します。
6. 必須項目を入力します。
   • Name: RESEND_API_KEY のような、わかりやすい参照名を入力します。文字、数字、アンダースコアを使用し、先頭は文字またはアンダースコアにしてください。
   • Value: プロバイダーから提供された認証情報を正確に入力します。
   • Description: Used to send account emails のように、そのキーの用途を説明します。認証情報の値は含めないでください。
7. 他のプロジェクトでもキーを再利用したい場合は、Save to Library を選択します。
8. Add を選択します。キーが保存されると、Atoms に Key added successfully と表示されます。

Test キーを追加する

新しいキーを追加できるのはワークスペースのオーナーのみです。キーの追加が必要な場合は、ワークスペースのオーナーに依頼してください。

保存済みのキーを Chat で使う

メッセージに値を直接入力する代わりに、保存済みのキーを参照してください。

1. Atoms のデスクトップ版でプロジェクトの Chat を開き、# と入力します。
2. キー を選択します。
3. 保存済みのキーを検索し、その名前を選択します。
4. そのキーの用途と、連携で実行したい内容をエージェントに伝えます。

# メニューは、保存済みキーの値をメッセージに挿入せずに、その参照を追加します。

Chat で保存済みのキーを参照する

保存済みのキーをテストする

1. App ビューアー で、そのキーを使用する簡単な操作を実行します。
2. テストメールの送信やテストデータの返却など、期待どおりの結果になることを確認します。
3. 表示されているエラーやログを確認し、キーの値が露出していないことを確認します。

サービスが test 用キーと live 用キーを別々に提供している場合は、アプリの構築中は test 用キーを使用してください。live 用キーは、アプリ公開後にのみ使用してください。テストに失敗した場合は、プロバイダーのダッシュボードで、そのキーが有効であり、要求された操作を実行する権限を持っていることを確認してください。 トラブルシューティング時にキーの値を Chat に貼り付けないでください。

キーの仕組みを理解する

キーを追加する前に、Atoms が何を保存するのか、また認証情報をどのように保護するのかを理解しておくと役立ちます。

Atoms が保存するもの

Atoms クラウド → キー には、API キーやアクセストークンなど、アプリが外部サービスに接続するために使用する認証情報が保存されます。

保存された各キーには、名前、説明、非公開の値があります。名前と説明はエージェントがキーを使う場面を理解するのに役立ち、非公開の値は Chat からは見えないままです。

キーの取得元

Atoms は外部サービス用の認証情報を作成したり提供したりしません。関連するサービスプロバイダーから取得する必要があります。権限の選択、キーのテスト、有効期限の有無の確認については、プロバイダーの指示に従ってください。

非公開認証情報を秘密に保つ

非公開の認証情報を Chat、ソースコード、ブラウザで実行されるコード、スクリーンショット、ログ、またはサポートメッセージに貼り付けないでください。 キー に保存し、その保存済みエントリを名前で参照してください。

非公開の値がすでに露出してしまった場合は、漏えいしたものとして扱い、プロバイダー側で無効化またはローテーションしてください。

非公開認証情報とブラウザで安全な認証情報

キー は保存された値を Public または Private としてラベル付けしません。 キー に値を保存しても、ブラウザ向けコードで安全に使えるようになるわけではありません。アプリがその値をブラウザで使用する場合、訪問者がそれを調べられる可能性があります。

認証情報をどこで使うかを決める前に、プロバイダーのドキュメントを確認してください。

• ブラウザ向けコードで値を使用するのは、プロバイダーが安全に公開できると明示している場合のみにしてください。
• 非公開認証情報は、アプリ訪問者に公開されないサーバーサイドまたはバックエンドのロジックに保持してください。

キーの環境と保存場所を選ぶ

キーを追加する際には、2 つの別々の判断が必要です。

• どの環境でそのキーを使用するか。
• そのキーをこのプロジェクト内にとどめるか、他のプロジェクトでも利用可能にするか。

環境を選ぶ

Option	使用されるタイミング
Test Keys	App ビューアー でアプリを開発およびテストしている間に使用されます。別の Production 用の値を追加しない場合、公開されたアプリでも Test の値が使用されます。
Production Keys	公開されたアプリで、別の live 用認証情報が必要な場合に使用されます。Production の値は公開プロセス中に追加され、Test の値とは別に管理されます。

キーの保存先を選ぶ

Option	使用するタイミング
In This Project	現在のプロジェクトでのみ使用すべきキーには、これを選択してください。
Key Library	複数のプロジェクトでキーを意図的に再利用したい場合に選択してください。Test キーを追加または更新する際に Save to Library を選択すると、ライブラリで利用可能になります。

環境と保存場所は独立しています。Test キーを Key Library に保存すると再利用可能になりますが、それによって Production の値になるわけではありません。

デフォルトでは In This Project を使用してください。キーをライブラリに保存するのは、プロジェクト間で共有すべきだと確信している場合のみにしてください。

別の Production 用の値を使う

保存済みのキーを使用するプロジェクトを公開する際、公開フローで Production Keys の設定を求められる場合があります。デフォルトでは、公開されたアプリは Test の値を使用します。別の認証情報を使用するには、Production を選択し、そのキー用に別の値を保存してください。

別の Production 用の値を使うのは、次のような場合です。

• プロバイダーが test 用と live 用で異なる認証情報を提供している。
• 開発中に使用した認証情報を、公開されたアプリでは使用したくない。

Production の値は公開フローを通じて作成されます。 Production Keys タブから New Key を選択して作成することはできません。公開済みアプリに Production の値が設定されると、Atoms クラウド → キー → Production Keys で確認できます。

アプリを公開または更新した後は、公開された Web サイトで該当するユーザージャーニーを再度実行し、Production キーが正しく動作することを確認してください。完全なデプロイ手順については、Publish and deploy を参照してください。

認証情報を更新またはローテーションする

保存済みの Test の値を更新する

1. Atoms クラウド → キー → Test Keys を開きます。
2. エントリの保存場所に応じて、In This Project または Key Library を開きます。
3. キーの Value または Description を選択し、更新した情報を入力してから、Update を選択します。
4. Save success が表示されるのを待ってから、影響を受けるフローを再度テストします。

計画的なキーローテーション

既存の認証情報がまだ安全で、アプリを中断せずに置き換えたい場合は、次の手順に従ってください。

1. サービスプロバイダーを通じて置き換え用の認証情報を作成します。
2. Atoms で Test の値を置き換え、App ビューアー で影響を受ける機能をテストします。
3. 公開されたアプリが別の Production の値を使用している場合は、それも置き換えて更新を公開します。
4. 公開された Web サイトで同じ機能をテストします。
5. 置き換えが正しく機能することを確認した後、プロバイダーを通じて古い認証情報を無効化します。

認証情報が露出した可能性がある場合

その認証情報は漏えいしたものとして扱い、すぐに対応してください。

1. サービスプロバイダーを通じて無効化または停止します。
2. 置き換え用の認証情報を作成します。
3. Atoms で該当する Test と Production の値を更新します。
4. App ビューアー と公開されたアプリの両方で、影響を受ける機能を再度テストします。
5. 可能であれば、ソースコード、Chat、スクリーンショット、ログから露出したコピーを削除します。

キーを削除したり、Atoms からその値を削除したりしても、元の認証情報が無効になるわけではありません。サービスプロバイダーを通じて無効化する必要があります。

認証情報を削除する

保存済みのキーを削除する前に、アプリがそれに依存していないことを確認してください。

1. そのキーを使用する機能を削除するか、参照先を別の保存済みキーに置き換えます。
2. 元の認証情報をサービスプロバイダー側で無効化し、もう使用できないようにします。
3. Atoms クラウド → キー を開き、非アクティブなエントリを見つけて、Delete を選択し、確認します。

キーの削除は元に戻せません。また、それを参照しているプレビューや古いチェックポイントが壊れる可能性もあります。 Delete が利用できない場合、そのキーはまだアクティブとしてマークされています。再度試す前に、そのキーへの参照をすべて削除または置き換えてください。

FAQ

Test キーは App Viewer では動作するのに、公開後は動作しません。なぜですか？

Test キーが App Viewer では動作するのに、公開されたアプリではキーが不足している、または空であるために失敗する場合は、次を確認してください。

1. 該当する Test または Production の値が、最後の公開の前に保存されたか後に保存されたかを確認します。後で保存された場合は、変更を反映するために再度公開してください。
2. 保存済みキーに正しい Test または Production の値が設定されていることを確認します。別の Production の値が設定されていない限り、公開されたアプリは Test の値を使用します。
3. 手がかりを得るために、下流サービスのエラーを確認します。"Unauthorized" は、その環境に対してキーが空または不正であることを示す場合が一般的です。

問題が解決しない場合は、Support に連絡し、次を含めてください。

• プロジェクトリンクまたは live URL
• 影響を受けているキー名と、問題があるのが Test と Production のどちらの値か
• 下流サービスからの完全なエラー
• 設定ページのサニタイズ済みスクリーンショット
• キー設定が公開前に保存されたか、公開後に保存されたか

重要: 提供するのはキー名のみです。シークレット値、パスワード、トークンは送信しないでください。