ほとんどのデプロイメントで必要な3つのキー
まずここから始めてください。より細かいカスタムスコープのキーが必要な場合のみ、以下の完全なパーミッションカタログを参照してください。推奨キーレイアウトおよびキーの作成も参照してください。
パーミッション
サーバーは固定のパーミッションカタログを強制します。各パーミッションは特定のHTTPルートへのアクセスを制限します。管理者キーはすべてのパーミッションを持ち、スコープ付きキーは作成時に付与したサブセットのみを持ちます。不明なパーミッション文字列はキー作成時に拒否されます。注意: 2つの有効なパーミッションは人間/ダッシュボード専用であり、APIキーには付与できません:orgs:admin（インスタンス管理、オペレーター専用）とkeys:updateです。どちらかを付与しようとするPOST /keysまたはPATCH /keys/:idリクエストはHTTP 422で拒否されます。ベアラーキーがキーを作成できても編集できない理由については、以下のkeys:updateの行を参照してください。
イベントの取り込みとクエリ
セッションと評価
ダッシュボード
保存済みクエリ（SQLコンポーザー）
AIアシスタント
APIキー
ダッシュボードユーザー
これらのパーミッションはダッシュボードのUsersページを支援しており、各メンバーに付与されたスコープがチップとして表示されます:
運用設定
アラートとインシデント
監査
注意: キーに監査機能を付与するには、audits:*を明示的に付与してください。Auditsが追加されたときに既存の付与者がどのように移行されたかについては、アップグレードと後方互換性に関する注記を参照してください。
受信者ピッカーエンドポイントGET /alerts/recipients（アラート編集者が通知できるメンバーのメール一覧を取得）はalerts:readまたはalerts:writeのいずれかを持つユーザーがアクセス可能であるため、アラート編集者はusers:readを付与されなくてもピッカーにデータを入力できます。
ダッシュボードビューワーにはdashboards:read（保存済みビューの読み込み）とevaluations:read（ヘルスメトリクスは評価データから計算）の両方が必要です。ダッシュボードの作成や編集を許可するにはdashboards:writeを、削除を許可するにはdashboards:deleteを付与してください。
/healthと/auth/*（OTPリクエスト、OTP検証、セッション確認、ログアウト）は設計上、認証不要です。これらはログインフローと生存確認プローブです。GET /access-grantersは有効なキーが必要ですが、特定のパーミッションは不要であるため、ログイン済みのすべてのユーザーがアクセス変更について連絡すべき管理者を確認できます。
パーミッションセット
パーミッションセットを使用すると、毎回個別のトークンを手作業で選択する代わりに、名前付きロールを適用できます。新しいダッシュボードユーザーやAPIキーごとに十数個のパーミッションを1つずつ選択する代わりに、セットを選択することで、割り当てられた全員が一貫した、確認可能な付与を受けます。カスタムセットを編集すると、既にそれに割り当てられているすべてのユーザーに新しい付与が再適用されるため、ロール変更は1回の編集で完了し、全メンバーを個別に更新する必要がありません。 すべてのオーガナイゼーションには3つの組み込みセットが初期設定されています:
3つの組み込みセットは変更不可です。その名前は常に同じ意味を持つため、
read-only、standard、adminはポリシーやオンボーディングで安全に参照できます。オペレーターはオーガナイゼーション固有のロールをモデル化するために追加のカスタムセットを作成できます（例: 「ダッシュボード作成者」ロールや「コレクターのみ」ロール）。
セットはダッシュボードに表示され、GET /permission-sets（一覧、users:readでゲート）およびPOST /permission-sets / PUT /permission-sets/:name / DELETE /permission-sets/:name（カスタムセットの作成、編集、削除、settings:writeでゲート）のAPIを通じて管理されます。組み込みセットの削除や編集は拒否されます。
セットメンバーシップは他の2つの機能を支援します:
DEFAULT_USER_PERMISSIONS（管理者が**+ new user**を開いたときに事前選択される付与）はデフォルトでstandardセットになります。agenteye-orgctlの--setフラグ（オペレーターメンバー管理）は名前付きセットからメンバーを開始し、その後--add/--removeで微調整します。
注意: セットにキーに割り当て不可能なパーミッションが含まれている場合（例: keys:updateを含むカスタムセット）、そのセットからキーをシードすると、割り当て不可能なトークンが除外されます。除外しない場合、サーバーはHTTP 422でキーを拒否します。ダッシュボードユーザーにはこの制限は適用されません。
ブートストラップ管理者キー
管理者キーは、オペレーターがゼロからアクセスを構築するための単一のルート認証情報です。このキーを使用して、他のすべてのスコープ付きキーを発行し、最初のダッシュボードユーザーを招待し、他のキーが存在する前にインスタンスを設定できます。これはkeys APIを通じて作成しない唯一のキーです。サーバーが最初の起動時にアクセス可能になるよう、環境からプロビジョニングされます。 サーバーでADMIN_KEY環境変数を設定してください。起動のたびに、サーバーはこの値をすべてのパーミッションを持つ管理者キーとしてアップサートします。
ローテートするには: ADMIN_KEYを新しいシークレットに変更してサーバーを再起動します。
オーガナイゼーションスコープ
オーガナイゼーション自体は、このkeys APIではなく、オペレーターによってアウトオブバンドで作成・管理されます。 orgとメンバーのライフサイクル（orgの作成/名前変更/削除/パージ、メンバーの追加/更新/削除）は**agenteye-orgctl** CLIで行います。これに対するHTTP APIやダッシュボードのボタンはありません。変わらないのは、org別APIキーは依然としてダッシュボード（またはこのkeys API経由）でorgメンバーによって発行されるという点です。
マルチorgデプロイメントでは、orgメンバーが（このkeys APIまたはダッシュボードのKeysページから）作成するすべてのキーは1つのオーガナイゼーションに属し、そのorgのデータのみを読み書きできます。orgはキー作成時にスタンプされ、すべてのリクエストで強制されます。2つのブートストラップキーのみが例外です: adminキー（ADMIN_KEYからシード）とdashboard-assistantキー（AGENT_API_KEYからシード）はインスタンススコープです（orgを持ちません）。ダッシュボードはadminキーで認証し、サインイン済みメンバーの代わりにorg別リクエストをプロキシします。シングルテナントデプロイメントではこれを意識する必要はありません。すべてのキーは組み込みのdefault orgに属します。
キーの作成
管理者キー（またはkeys:createパーミッションを持つキー）を使用して、追加のスコープ付きキーを作成します。
コレクターキー（取り込みのみ）
ダッシュボードキー（読み取りのみ）
keyの値は自分で指定します。強力なシークレットを選択し、安全に保管してください。（ダッシュボードは逆の動作をします: 強力なシークレットを生成し、作成時に一度だけ表示します。ダッシュボードでのキー管理を参照してください。）レスポンスでキーが作成されたことを確認できます:
キーの一覧表示
キーの無効化
無効化するとキーレコードを削除せずに、即座にアクセスが失効します。キーの再生成
既存キーの新しいシークレットを生成します。古いシークレットは即座に無効化されます。ダッシュボードでのキー管理
ダッシュボードのKeysページでは、上記のすべての操作をUIで行えます。一覧を表示するにはkeys:readパーミッションを持つキーが必要で、作成/編集/無効化/再生成の操作にはそれぞれkeys:create / keys:update / keys:disable / keys:regenerateが必要です。キーのパーミッションの編集（keys:update）とキーの作成（keys:create）は別々になっているため、オペレーターにキーの発行権限を付与しつつ既存キーの再スコープ権限を与えない、またはその逆が可能です。管理者キーはこれらすべてをカバーします。
ダッシュボードからキーを作成する場合、シークレットを入力する必要はありません。ダッシュボードが強力なシークレットを生成し、作成時に一度だけ表示します。すぐにコピーして安全に保管してください。再生成の場合と同様、二度と表示されません。パーミッションを直接選択することも、パーミッションセットからシードすることもできます（以下を参照）。
推奨キーレイアウト
注意: アシスタントのキーはAGENT_API_KEY環境変数（エージェントがAGENTEYE_API_KEYとして提示するのと同じシークレット）からサーバーによって自動的にシードされます。手動のキー発行手順も管理者キーの関与もありません。パーミッションはソースコードに固定されているため、設定ミスによってスコープが拡大することはありません: イベント/評価/ダッシュボード全体の読み取り、加えてクエリ作成フロー「AIにクエリを書いてもらう」のためのダッシュボード書き込みとクエリ読み取り/書き込み/実行。すべてのSQLは引き続き同じ読み取り専用ロールとガードされたSQLパスを通過するため、これはデータサーフェスではなく作成サーフェスを拡大します。破壊的な操作（queries:delete、dashboards:delete）は意図的にアシスタントキーから除外されています。adminキーと同様に保護されています: keys APIを通じて無効化や再生成はできず、AGENT_API_KEYを変更して再起動することでのみローテートできます。ダッシュボードユーザーがアシスタントを表示して使用するには、追加でagent:useパーミッションが必要です。セルフインストルメンテーションを有効にする場合は、アシスタントにevents:add専用の別キーを付与してください。
アップグレードと後方互換性に関する注記
これらは既存のインスタンスをアップグレードする場合にのみ必要です。新規デプロイメントはスキップしてください。Auditsが追加された際、既存の付与者はアラートと同じロール形状に沿って拡張されました:alerts:readを持つすべてのユーザーとパーミッションセットにはaudits:readが追加され、alerts:writeを持つすべてのユーザーにはaudits:writeが追加されました。既存のAPIキーは拡張されませんでした。監査機能が必要なキーにはaudits:*を明示的に付与してください。
レガシーなalerts:ackトークンの保存済み付与はincidents:ackとして解析されるため、オンコール担当者はキーを再発行せずにアクセスを維持できます。このトークンはダッシュボードのユーザーエディターから割り当てられなくなりました。マトリックスでは代わりにincidents:ackが提供されています。
次のステップ
- Python SDK: エージェントコードがイベント送信時にどのように認証するか。
- Security: サインイン、アクセス制御、オーガナイゼーションごとのデータ分離の仕組み。