API 密钥

API 密钥控制谁以及什么可以访问您的 Failproof AI Observability 服务器，使采集器可以发送事件而无需获得读取或管理员权限。每个密钥携带一个或多个权限，每个权限控制特定的服务器路由；您只需授予某项工作所需的少量权限。大多数部署只需创建三种类型的密钥。

大多数部署所需的 3 种密钥

密钥	权限	使用者
采集器密钥	`events:add`	每台 Agent 机器上的 `agenteye-collector`，用于发送事件。
仪表板读取密钥	`events:read`、`keys:read`	查询数据但不修改数据的只读操作员或集成。
引导管理员密钥	所有权限	首次启动实例（及仪表板）的操作员。由 `ADMIN_KEY` 环境变量初始化。参见引导管理员密钥。

从这里开始。仅在需要更窄的自定义作用域密钥时，才参考下方的完整权限目录。另请参阅推荐密钥布局和创建密钥。

权限

服务器执行固定的权限目录；每个权限控制特定的 HTTP 路由。管理员密钥拥有所有权限；作用域密钥只拥有您在创建时授予的子集。创建密钥时，未知的权限字符串将被拒绝。

注意： 有两个有效权限仅供人工/仪表板使用，不能授予 API 密钥：orgs:admin（实例管理，仅限操作员）和 keys:update。尝试授予其中任一权限的 POST /keys 或 PATCH /keys/:id 请求将被拒绝并返回 HTTP 422。请参阅下方 keys:update 行，了解为何持有者密钥可以创建密钥但永远无法编辑密钥。

事件摄取与查询

权限	HTTP 路由	允许的操作
`events:add`	`POST /events`	从采集器摄取批量事件。这是采集器唯一需要的权限。
`events:read`	`GET /events`、`GET /events/latency_aggregate`、`GET /events/environments`、`GET /events/models`、`GET /sessions/:session_id/export`	查询事件、列出已知环境、列出数据中出现的模型标识符（供模型视图和模型过滤器使用）、计算为热图/百分位带提供支持的延迟聚合，以及将会话导出为 JSONL。共享筛选栏分面端点 `GET /events/environments` 和 `GET /events/agent_ids` 可通过 `events:read` 或 `evaluations:read` 任一权限访问，因此会话页面（受 `evaluations:read` 控制）可复用相同的按组织分面。`GET /events/models` 不在其中：它需要 `events:read`，因此仅持有 `evaluations:read` 的主体访问时将收到 403。

会话与评估

权限	HTTP 路由	允许的操作
`evaluations:read`	`GET /sessions`、`GET /evaluations`、`GET /evaluations/aggregate`、`GET /evaluations/environments`、`GET /evaluation-jobs`	列出会话、读取评估结果、仪表板使用的汇总评估健康状况，以及评估任务工作队列状态。
`evaluations:trigger`	`POST /sessions/:session_id/re-evaluate`	手动为已完成的会话排队重新评估。

仪表板

权限	HTTP 路由	允许的操作
`dashboards:read`	`GET /dashboards`、`GET /dashboards/:id`、`GET /dashboards/:id/tiles`	列出仪表板、加载某个仪表板并读取其磁贴。
`dashboards:write`	`POST /dashboards`、`PUT /dashboards/:id`、`POST /dashboards/:id/tiles`、`PUT /dashboards/:id/tiles/:tile_id`、`DELETE /dashboards/:id/tiles/:tile_id`、`PUT /dashboards/:id/tiles/layout`	创建和编辑仪表板、添加/编辑/删除磁贴，以及重新排列磁贴网格。
`dashboards:delete`	`DELETE /dashboards/:id`	删除整个仪表板（磁贴级别的删除属于 `dashboards:write`）。

已保存查询（SQL 编辑器）

权限	HTTP 路由	允许的操作
`queries:read`	`GET /queries`、`GET /queries/:id`、`GET /queries/schema`	列出已保存的查询、加载某个查询，并检查编辑器所针对的只读架构。
`queries:write`	`POST /queries`、`PUT /queries/:id`	创建和编辑已保存的查询。SQL 仍然通过与 `queries:run` 调用相同的只读角色和受保护的 SQL 检查进行路由。
`queries:delete`	`DELETE /queries/:id`	删除已保存的查询。
`queries:run`	`POST /queries/run`	针对编辑器使用的只读角色执行已保存或临时 SQL。

AI 助手

权限	HTTP 路由	允许的操作
`agent:use`	`GET /agent/conversations`、`POST /agent/conversations`、`GET /agent/conversations/:id`、`PATCH /agent/conversations/:id`、`DELETE /agent/conversations/:id`、`PUT /agent/conversations/:id/messages`	与 AI 助手对话并管理您自己的（私人）会话。在用户上需要此权限才能看到助手面板；助手自身的密钥为 `dashboard-assistant`，单独初始化（见下文）。

权限	HTTP 路由	允许的操作
`keys:create`	`POST /keys`	创建新的作用域 API 密钥。不授予编辑现有密钥权限的能力（那是 `keys:update`）。
`keys:read`	`GET /keys`	列出现有密钥。此端点永远不会返回密钥密文。
`keys:update`	`PATCH /keys/:id`	编辑现有密钥的权限。这是一个仅供人工/仪表板使用的权限；不能分配给 API 密钥（持有者密钥可以创建密钥，但永远无法编辑密钥）。
`keys:disable`	`POST /keys/:id/disable`	吊销密钥。受保护的密钥（`admin`、`dashboard-assistant`）无法被禁用；请通过更改环境变量并重启来轮换它们。
`keys:regenerate`	`POST /keys/:id/regenerate`	轮换密钥的密文。受保护的密钥无法通过此路由重新生成。

仪表板用户

权限	HTTP 路由	允许的操作
`users:create`	`POST /users`、`GET /users/defaults`	邀请新的仪表板用户（发送电子邮件及一次性密码 (OTP) 登录），并读取用于预填邀请表单的仪表板配置默认权限集。
`users:read`	`GET /users`、`GET /users/:id`	列出用户并加载单个用户记录。
`users:update`	`PUT /users/:id`	编辑用户的权限。更新会向受影响的用户发送权限变更邮件，并在其下一次请求时生效；无需重新登录。
`users:delete`	`DELETE /users/:id`、`POST /users/:id/enable`	禁用用户（立即吊销其会话）并重新启用之前被禁用的用户。

这些权限支撑仪表板的用户页面，每个成员授予的作用域以标签形式显示：

用户页面：每个仪表板用户一张卡片，显示其电子邮件、已授予的权限以及编辑/禁用控件

操作设置

权限	HTTP 路由	允许的操作
`settings:read`	`GET /settings`、`GET /settings/schema`、`GET /settings/model-context-windows`、`GET /settings/model-context-windows/resolve`	查看仪表板管理的操作设置及其元数据；列出每个模型的上下文窗口覆盖值；以及解析模型的有效窗口。
`settings:write`	`PUT /settings/:key`、`PUT /settings/model-context-windows`、`DELETE /settings/model-context-windows`	编辑操作设置，以及添加、更改或删除每个模型的上下文窗口覆盖值。更改会影响新事件，无需重启服务器。

告警与事件

权限	HTTP 路由	允许的操作
`alerts:read`	`GET /alerts`、`GET /alerts/:id`	查看已配置的告警定义。
`alerts:write`	`POST /alerts`、`PUT /alerts/:id`、`DELETE /alerts/:id`、`POST /alerts/:id/test`	创建、编辑、删除和测试触发告警定义。
`incidents:read`	`GET /alerts/incidents`、`GET /alerts/incidents/:iid`、`GET /alerts/incidents/:iid/comments`、`GET /alerts/incidents/:iid/subscribers`	查看事件及其分类记录。
`incidents:write`	`POST /alerts/:id/incidents`	针对现有告警手动开启一个事件。
`incidents:ack`	`POST /alerts/incidents/:iid/ack`、`POST /alerts/incidents/:iid/assign`、`POST /alerts/incidents/:iid/resolve`、`POST /alerts/incidents/:iid/comments`、`POST /alerts/incidents/:iid/subscribe`、`POST /alerts/incidents/:iid/unsubscribe`	确认、分配、解决事件并对其进行评论。

审计

权限	HTTP 路由	允许的操作
`audits:read`	`GET /audits`、`GET /audits/:id`、`GET /audits/:id/runs`、`GET /audits/findings`、`GET /audits/findings/:fid`	查看审计定义、运行历史和发现结果。
`audits:write`	`POST /audits`、`PUT /audits/:id`、`DELETE /audits/:id`、`POST /audits/:id/run`、`POST /audits/findings/:fid/status`	创建、编辑、删除和运行审计；对发现结果进行分类（确认/静默/忽略/解决/重新开启/分配）。

注意： 要为密钥授予审计权限，请显式授予 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 密钥逐一选择十几个权限，不如选择一个集合，分配到该集合的所有人都持有一致且可审查的授权。编辑自定义集合会将新授权重新应用于已分配该集合的每个用户，因此角色变更只需一次编辑，而无需逐一遍历每个成员。每个组织初始化时都带有三个内置集合：

集合	权限	适用对象
`read-only`	`events:read`、`keys:read`、`users:read`、`evaluations:read`、`dashboards:read`、`queries:read`、`settings:read`、`alerts:read`、`audits:read`、`incidents:read`	对所有操作界面的只读访问。
`standard`	`read-only` 中的所有权限，加上 `evaluations:trigger`、`queries:run`、`incidents:ack`、`agent:use`	只读权限加上日常值班操作：运行查询、重新评估会话、确认事件以及使用 AI 助手。
`admin`	所有可分配的权限	对组织的完全控制。

三个内置集合是不可变的；其名称始终代表相同含义，因此 read-only、standard 和 admin 可在策略和入职流程中安全引用。操作员可以创建额外的自定义集合，以建模特定于您组织的角色（例如”仪表板作者”角色或”仅采集器”角色）。集合在仪表板中展示，并通过 API 进行管理：GET /permission-sets（列出，受 users:read 控制）以及 POST /permission-sets / PUT /permission-sets/:name / DELETE /permission-sets/:name（创建、编辑、删除自定义集合，受 settings:write 控制）。删除或编辑内置集合的请求将被拒绝。集合成员资格支撑着另外两项功能：

DEFAULT_USER_PERMISSIONS（管理员打开 + 新用户 时预选的授权）默认为 standard 集合。
agenteye-orgctl 上的 --set 标志（操作员成员管理）从命名集合初始化成员，然后您可以使用 --add / --remove 进行微调。

注意： 当集合包含不可分配给密钥的权限时（例如携带 keys:update 的自定义集合），从该集合初始化密钥时会删除不可分配的令牌；否则服务器将以 HTTP 422 拒绝该密钥。仪表板用户不受此限制。

引导管理员密钥

管理员密钥是单一根凭证，允许操作员从零开始建立访问权限：使用它可以创建所有其他作用域密钥、邀请第一批仪表板用户，并在任何其他密钥存在之前配置实例。这是唯一不通过密钥 API 创建的密钥；它从环境中配置，以便服务器在首次启动时即可访问。在服务器上设置 ADMIN_KEY 环境变量。每次启动时，服务器会将此值更新插入为具有所有权限的管理员密钥。轮换方式：将 ADMIN_KEY 更改为新密文并重启服务器。

组织作用域

组织本身由操作员在带外创建和管理，而不是通过此密钥 API。 组织和成员的生命周期（创建/重命名/删除/清除组织；添加/更新/移除成员）通过 agenteye-orgctl CLI 完成；没有对应的 HTTP API 或仪表板按钮。不变的是：按组织的 API 密钥仍由组织成员在仪表板（或通过此密钥 API）中创建。 在多组织部署中，组织成员创建的每个密钥（通过此密钥 API 或仪表板密钥页面）都属于一个组织，只能读取或写入该组织的数据；组织在创建时被标记到密钥上，并在每次请求时强制执行。两个引导密钥是唯一的例外：admin 密钥（从 ADMIN_KEY 初始化）和 dashboard-assistant 密钥（从 AGENT_API_KEY 初始化）是实例作用域（不携带组织信息）。仪表板使用 admin 密钥进行身份验证，以便代表已登录的成员代理每个组织的请求。单租户部署无需考虑这一点；所有密钥都属于内置的 default 组织。

创建密钥

使用管理员密钥（或任何具有 keys:create 权限的密钥）来创建其他作用域密钥。

采集器密钥（仅摄取）

curl -s -X POST http://your-server/keys \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-collector",
    "key": "your-collector-secret",
    "permissions": ["events:add"]
  }'

仪表板密钥（只读）

curl -s -X POST http://your-server/keys \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dashboard",
    "key": "your-dashboard-secret",
    "permissions": ["events:read", "keys:read"]
  }'

通过 HTTP API 创建密钥时，您需要自行提供 key 值；请选择强密文并安全存储。（仪表板的方式相反：它会为您生成强密文，并在创建时仅显示一次；参见仪表板中的密钥管理。）响应确认密钥已创建：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "prod-collector",
  "permissions": ["events:add"],
  "created_at": "2026-04-01T12:00:00Z"
}

列出密钥

curl -s http://your-server/keys \
  -H "Authorization: Bearer $ADMIN_KEY"

列表响应中不返回密钥密文，只返回 ID、名称和权限。

禁用密钥

禁用会立即吊销访问权限，而不删除密钥记录。

curl -s -X POST http://your-server/keys/<id>/disable \
  -H "Authorization: Bearer $ADMIN_KEY"

重新生成密钥

为现有密钥生成新密文。旧密文立即失效。

curl -s -X POST http://your-server/keys/<id>/regenerate \
  -H "Authorization: Bearer $ADMIN_KEY"

响应包含新的明文密文，仅显示一次。

仪表板中的密钥管理

仪表板中的密钥页面为上述所有操作提供了 UI。您需要具有 keys:read 权限的密钥才能查看列表，以及分别具有 keys:create / keys:update / keys:disable / keys:regenerate 权限才能执行创建/编辑/禁用/重新生成操作。编辑密钥权限（keys:update）与创建密钥（keys:create）是分开的，因此您可以授予操作员创建密钥的能力，而不授予重新界定现有密钥作用域的能力，反之亦然。管理员密钥涵盖所有这些操作。从仪表板创建密钥时，您无需提供密文；仪表板会为您生成强密文，并在创建时仅显示一次。请立即复制并安全存储；与重新生成密钥一样，它不会再次显示。您仍然可以直接选择密钥的权限，或从权限集初始化（见下文）。

API 密钥页面：每个密钥一张卡片，显示其名称、已授予的权限和创建时间，以及重新生成和禁用操作；受保护的密钥（如 admin）会被标记

密钥	权限	使用者
`admin`（通过 `ADMIN_KEY` 环境变量引导）	所有	运维/配置，以及仪表板（使用 `ADMIN_KEY` 进行身份验证，通过权限检查代理用户请求）
每主机采集器密钥	`events:add`	每台 Agent 机器上的采集器
`dashboard-assistant`（通过 `AGENT_API_KEY` 环境变量引导）	`events:read`、`evaluations:read`、`dashboards:read`、`dashboards:write`、`queries:read`、`queries:write`、`queries:run`	AI 助手，自动初始化，受保护；无法通过 API 编辑
助手遥测密钥（可选）	`events:add`	AI 助手自我检测（如已启用）

升级和向后兼容性说明

仅在升级现有实例时才需要以下内容；新部署可跳过。

审计功能上线时，现有授权者按照与告警相同的角色形态进行了扩展：每个持有 alerts:read 的用户和权限集获得了 audits:read，每个持有 alerts:write 的用户获得了 audits:write。现有 API 密钥未被扩展。如果密钥需要审计功能，请显式授予 audits:*。

旧版 alerts:ack 令牌的存储授权被解析为 incidents:ack，以便值班人员无需重新创建密钥即可保留访问权限。该令牌不再可从仪表板用户编辑器分配；矩阵现在提供 incidents:ack。

后续步骤

Python SDK：您的 Agent 代码在发送事件时如何进行身份验证。
安全性：登录、访问控制和每个组织的数据隔离如何工作。

Overview

Features

SDK and CLI

Administration

API 密钥

大多数部署所需的 3 种密钥

权限

事件摄取与查询

会话与评估

仪表板

已保存查询（SQL 编辑器）

AI 助手

API 密钥

仪表板用户

操作设置

告警与事件

审计

权限集

引导管理员密钥

组织作用域

创建密钥

采集器密钥（仅摄取）

仪表板密钥（只读）

列出密钥

禁用密钥

重新生成密钥

仪表板中的密钥管理

推荐密钥布局

升级和向后兼容性说明

后续步骤

​大多数部署所需的 3 种密钥

​权限

​事件摄取与查询

​会话与评估

​仪表板

​已保存查询（SQL 编辑器）

​AI 助手

​API 密钥

​仪表板用户

​操作设置

​告警与事件

​审计

​权限集

​引导管理员密钥

​组织作用域

​创建密钥

​采集器密钥（仅摄取）

​仪表板密钥（只读）

​列出密钥

​禁用密钥

​重新生成密钥

​仪表板中的密钥管理

​推荐密钥布局

​升级和向后兼容性说明

​后续步骤

大多数部署所需的 3 种密钥

权限

事件摄取与查询

会话与评估

仪表板

已保存查询（SQL 编辑器）

AI 助手

API 密钥

仪表板用户

操作设置

告警与事件

审计

权限集

引导管理员密钥

组织作用域

创建密钥

采集器密钥（仅摄取）

仪表板密钥（只读）

列出密钥

禁用密钥

重新生成密钥

仪表板中的密钥管理

推荐密钥布局

升级和向后兼容性说明

后续步骤