キーとシークレット

キー を使用する前に、プロジェクトを 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. 表示されているエラーやログを確認し、キーの値が露出していないことを確認します。

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

キーの仕組みを理解する

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

Atoms が保存するもの

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

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

キーの入手先

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

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

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

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

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

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

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

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

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

キーを追加する際には、次の 2 つを別々に決める必要があります。

• どの環境でそのキーを使用するか。
• そのキーをこのプロジェクト内だけに保持するか、他のプロジェクトでも使えるようにするか。

環境を選ぶ

Option	When it is used
Test Keys	App ビューアー でアプリを開発およびテストしている間に使用されます。別の Production の値を追加しない場合、公開済みアプリでも Test の値が使用されます。
Production Keys	公開済みアプリで別の本番用認証情報が必要な場合に使用されます。Production の値は公開プロセス中に追加され、Test の値とは別に管理されます。

キーの保存場所を選ぶ

Option	When to use it
In This Project	現在のプロジェクトでのみ使用すべきキーの場合に選択します。
Key Library	複数のプロジェクトでキーを意図的に再利用したい場合に選択します。Test キーを追加または更新する際に Save to Library を選択すると、ライブラリで利用できるようになります。

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

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

別の Production の値を使う

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

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

• プロバイダーがテスト用と本番用で異なる認証情報を提供している。
• 開発中に使用した認証情報を、公開済みアプリでは使用したくない。

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 に連絡し、次を含めてください。

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

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