API Keys

​

3 key mà hầu hết các triển khai cần

​

Quyền

Lưu ý: Hai quyền hợp lệ chỉ dành cho dashboard con người và không thể được cấp cho API key: orgs:admin (quản trị instance, chỉ dành cho nhà điều hành) và keys:update. Một yêu cầu POST /keys hoặc PATCH /keys/:id cố gắng cấp một trong hai quyền bị từ chối với HTTP 422. Xem hàng keys:update dưới đây để biết lý do tại sao một bearer key có thể tạo key nhưng không bao giờ chỉnh sửa chúng.

​

Events ingest & query

​

Sessions & evaluations

​

Dashboards

​

Saved queries (SQL composer)

​

AI assistant

​

API keys

​

Dashboard users

​

Operational settings

​

Alerts & incidents

​

Audits

Lưu ý: Để cấp cho key bề mặt audit, cấp audits:* cho nó một cách rõ ràng. Xem Upgrade and backward-compatibility notes để biết các grantee hiện tại được di chuyển khi Audits vận hành.

Endpoint bộ chọn người nhận GET /alerts/recipients (liệt kê các email thành viên mà trình chỉnh sửa cảnh báo có thể thông báo) có thể truy cập được bởi một người nắm giữ bất kỳ alerts:read hoặc alerts:write, vì vậy các trình chỉnh sửa cảnh báo có thể điền bộ chọn mà không được cấp users:read.

Một người xem dashboard cần cả hai dashboards:read (để tải các chế độ xem đã lưu) và evaluations:read (các chỉ số sức khỏe được tính từ dữ liệu đánh giá). Cấp dashboards:write để cho phép người dùng tạo hoặc chỉnh sửa dashboard, và dashboards:delete để xóa chúng.

/health và /auth/* (yêu cầu OTP, xác minh OTP, kiểm tra phiên, đăng xuất) không được xác thực theo thiết kế; chúng là dòng đăng nhập và liveness probe. GET /access-granters yêu cầu một key hợp lệ nhưng không có quyền cụ thể nào, vì vậy bất kỳ người dùng đã đăng nhập nào cũng có thể xem những admin nào để liên hệ về các thay đổi truy cập.

​

Permission Sets

• DEFAULT_USER_PERMISSIONS (cấp được chọn trước khi admin mở + new user) mặc định cho tập hợp standard.
• Flag --set trên agenteye-orgctl (quản lý thành viên nhà điều hành) bắt đầu một thành viên từ một tập hợp được đặt tên, mà sau đó bạn tinh chỉnh với --add / --remove.

Lưu ý: Khi một tập hợp bao gồm một quyền không thể gán key (ví dụ: một tập hợp tùy chỉnh mang keys:update), khởi tạo một key từ tập hợp đó sẽ loại bỏ các token không thể gán; máy chủ sẽ từ chối key khác với HTTP 422. Những người dùng dashboard không phải chịu hạn chế đó.

​

Bootstrap Admin Key

​

Organization scoping

​

Creating Keys

​

Collector key (ingest only)

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"]
  }'

​

Dashboard key (read only)

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"]
  }'

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

​

Listing Keys

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

​

Disabling a Key

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

​

Regenerating a Key

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

​

Key Management in the Dashboard

​

Recommended Key Layout

Lưu ý: Key của trợ lý được khởi tạo tự động bởi máy chủ từ biến env AGENT_API_KEY (secret giống nhau mà agent trình bày dưới dạng AGENTEYE_API_KEY); không có bước tạo key thủ công và không có admin key liên quan. Các quyền của nó được khắc phục trong source code vì vậy phạm vi không thể được mở rộng bởi cấu hình sai: đọc trên sự kiện / đánh giá / dashboard, cộng với dashboards-write và queries-read / write / run cho dòng tác giả “Ask AI to write a query”. Tất cả SQL vẫn đi qua cùng một role chỉ đọc và đường dẫn SQL được bảo vệ như một truy vấn do người dùng viết, vì vậy điều này mở rộng bề mặt tác giả, không phải bề mặt dữ liệu; các hoạt động phá hủy (queries:delete, dashboards:delete) cố ý ở ngoài assistant key. Giống như key admin, nó được bảo vệ: nó không thể bị vô hiệu hóa hoặc tái tạo thông qua keys API, chỉ xoay bằng cách thay đổi AGENT_API_KEY và khởi động lại. Người dùng dashboard cần quyền agent:use để xem và sử dụng trợ lý. Nếu bạn bật self-instrumentation, hãy cung cấp cho trợ lý một key riêng chỉ events:add.

​

Upgrade and backward-compatibility notes

Khi Audits được vận hành, các grantee hiện tại được mở rộng cùng các hình dạng vai trò với alert: mỗi người dùng và permission set nắm giữ alerts:read đã đạt được audits:read, và mỗi người nắm giữ alerts:write đã đạt được audits:write. Các API key hiện tại không được mở rộng. Cấp audits:* cho một key một cách rõ ràng nếu nó cần bề mặt audit.

Cấp của legacy token alerts:ack được lưu trữ được phân tích cú pháp thành incidents:ack vì vậy on-caller vẫn giữ quyền truy cập mà không cần đổi key. Token không còn có thể gán từ trình chỉnh sửa người dùng của dashboard; ma trận cung cấp incidents:ack thay thế.

​

Các bước tiếp theo

• Python SDK: cách mã agent của bạn xác thực khi gửi sự kiện.
• Security: cách đăng nhập, kiểm soát truy cập, và cách cô lập dữ liệu mỗi tổ chức hoạt động.