API 키

AgentEye는 서버 접근을 제어하기 위해 세분화된 API 키를 사용합니다. 각 키는 하나 이상의 권한을 보유하며, 이 권한이 해당 키가 수행할 수 있는 작업을 결정합니다.

권한

서버는 고정된 권한 목록을 강제하며, 각 권한은 특정 HTTP 라우트에 대한 접근을 제어합니다. admin 키는 모든 권한을 보유하고, 범위가 지정된(scoped) 키는 생성 시 부여한 권한의 하위 집합을 보유합니다. 키를 생성할 때 알 수 없는 권한 문자열이 포함되면 거부됩니다.

키에 할당할 수 없음. 두 가지 유효한 권한은 사람/대시보드 전용이며 API 키에 부여할 수 없습니다: orgs:admin(인스턴스 관리, 운영자 전용)과 keys:update. POST /keys 또는 PATCH /keys/:id 요청에서 이 둘 중 하나를 부여하려 하면 HTTP 422로 거부됩니다. Bearer 키가 키를 생성할 수는 있지만 편집할 수 없는 이유는 아래 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`	이벤트 조회, 알려진 환경 목록, 데이터에서 확인된 모델 식별자 목록(Models 뷰 및 모델 필터에서 사용), 히트맵/백분위 밴드를 구동하는 지연 집계 계산, 그리고 세션을 JSONL로 내보내기를 허용합니다. 공유 필터바 패싯 엔드포인트인 `GET /events/environments`와 `GET /events/models`는 `events:read` 또는 `evaluations:read` 중 하나로 접근할 수 있으므로, (`evaluations:read`로 제한된) 세션 페이지가 동일한 org별 패싯을 재사용할 수 있습니다.

세션 및 평가

권한	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`	저장된 쿼리 목록, 개별 쿼리 로드, 작성기가 대상으로 하는 읽기 전용 ClickHouse 스키마 검사를 허용합니다.
`queries:write`	`POST /queries`, `PUT /queries/:id`	저장된 쿼리를 생성하고 편집합니다. SQL은 `queries:run` 호출과 동일한 읽기 전용 역할 및 `sql_guard` 검사를 통해 라우팅됩니다.
`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 키에 할당할 수 없습니다(Bearer 키는 키를 생성할 수 있지만 편집할 수 없습니다).
`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`	사용자를 비활성화(즉시 세션 폐지)하거나 이전에 비활성화된 사용자를 다시 활성화합니다.

이 권한들은 대시보드의 Users 페이지를 지원하며, 각 멤버에게 부여된 범위가 칩 형태로 표시됩니다:

Users 페이지: 각 대시보드 사용자의 이메일, 부여된 권한, 편집/비활성화 컨트롤이 포함된 카드

운영 설정

권한	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`	인시던트를 확인(acknowledge), 담당자 지정, 해결, 댓글 작성, 구독/구독 취소합니다.

감사

권한	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 기능이 출시될 때, 기존 권한 부여자는 알림과 동일한 역할 형태로 확장되었습니다: alerts:read를 보유한 모든 사용자와 권한 집합에는 audits:read가 추가되었고, alerts:write를 보유한 모든 권한 부여자에게는 audits:write가 추가되었습니다. 기존 API 키는 확장되지 않았습니다 — 감사 기능이 필요한 키에는 audits:*를 명시적으로 부여하세요.

레거시 alerts:ack 토큰의 저장된 권한 부여는 incidents:ack로 파싱되므로, 온콜 담당자는 키를 재발급하지 않고도 접근을 유지할 수 있습니다. 이 토큰은 더 이상 대시보드 사용자 편집기에서 할당할 수 없으며, 매트릭스에서는 incidents:ack를 제공합니다.

수신자 선택 엔드포인트 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(관리자가 + new user를 열 때 사전 선택되는 권한 부여)는 기본적으로 standard 집합으로 설정됩니다. 배포를 참조하세요.
agenteye-orgctl의 --set 플래그(운영자 멤버 관리)는 명명된 집합으로 멤버를 시작한 후 --add / --remove로 세부 조정합니다. 테넌트 관리를 참조하세요.

집합에 키 할당 불가 권한(예: keys:update를 포함한 커스텀 집합)이 포함된 경우, 해당 집합에서 키를 시딩하면 할당 불가 토큰이 제외됩니다. 그렇지 않으면 서버가 HTTP 422로 키를 거부합니다. 대시보드 사용자에게는 이 제한이 적용되지 않습니다.

부트스트랩 Admin 키

admin 키는 운영자가 아무것도 없는 상태에서 접근을 구성할 수 있게 해주는 단일 루트 자격 증명입니다. 이 키로 다른 모든 범위 지정 키를 생성하고, 첫 번째 대시보드 사용자를 초대하며, 다른 키가 존재하기 전에 인스턴스를 구성할 수 있습니다. 이 키는 keys API를 통해 생성하지 않는 유일한 키로, 서버가 처음 부팅될 때 접근 가능하도록 환경에서 프로비저닝됩니다. 서버에 ADMIN_KEY 환경 변수를 설정하세요. 매 시작 시 서버는 이 값을 모든 권한을 가진 admin 키로 upsert합니다. 교체하려면: ADMIN_KEY를 새 시크릿으로 변경하고 서버를 재시작하세요.

조직 범위

조직 자체는 운영자가 대역 외(out-of-band)로 생성하고 관리하며, 이 keys API를 통해 관리하지 않습니다. 조직 및 멤버 수명 주기(조직 생성/이름 변경/삭제/제거, 멤버 추가/업데이트/삭제)는 서버 파드 내부에서 실행되는 agenteye-orgctl CLI로 수행하며, HTTP API나 대시보드 버튼이 없습니다. 테넌트 관리를 참조하세요. 변경되지 않는 것: org별 API 키는 여전히 대시보드(또는 이 keys API를 통해)에서 org 멤버가 발급합니다. 다중 org 배포에서 org 멤버가 생성하는 모든 키(이 keys API 또는 대시보드 Keys 페이지를 통해)는 하나의 조직에 속하며 해당 org의 데이터만 읽거나 쓸 수 있습니다. org는 키 생성 시 스탬핑되어 모든 요청에서 강제 적용됩니다. 두 가지 부트스트랩 키만 예외입니다: admin 키(ADMIN_KEY에서 시딩)와 dashboard-assistant 키(AGENT_API_KEY에서 시딩)는 인스턴스 범위(org 없음)를 가집니다. 대시보드 컨테이너는 admin 키로 인증하여 로그인된 멤버를 대신해 org별 요청을 프록시합니다. 단일 테넌트 배포에서는 이를 고려할 필요가 없습니다. 모든 키는 기본 제공 default org에 속합니다.

키 생성

추가 범위 지정 키를 생성하려면 admin 키(또는 keys:create 권한을 가진 키)를 사용하세요.

수집기 키 (수집 전용)

curl -s -X POST http://your-server:8080/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:8080/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:8080/keys \
  -H "Authorization: Bearer $ADMIN_KEY"

키 시크릿은 목록 응답에 반환되지 않으며, ID, 이름, 권한만 반환됩니다.

키 비활성화

비활성화하면 키 레코드를 삭제하지 않고도 즉시 접근이 폐지됩니다.

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

키 재생성

기존 키에 대해 새 시크릿을 생성합니다. 기존 시크릿은 즉시 무효화됩니다.

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

응답에는 새로운 평문 시크릿이 포함되며, 한 번만 표시됩니다.

대시보드에서의 키 관리

대시보드의 Keys 페이지는 위의 모든 작업을 위한 UI를 제공합니다. 목록을 보려면 keys:read 권한이 있는 키가 필요하고, 생성/편집/비활성화/재생성 작업에는 각각 keys:create / keys:update / keys:disable / keys:regenerate가 필요합니다. 키의 권한 편집(keys:update)은 키 생성(keys:create)과 별개이므로, 운영자에게 기존 키의 범위를 재설정하는 권한 없이 키 발급 권한만 부여하거나 그 반대로 설정할 수 있습니다. admin 키는 이 모든 권한을 포함합니다. 대시보드에서 키를 생성할 때 시크릿을 직접 입력하지 않아도 됩니다. 대시보드가 강력한 시크릿을 자동으로 생성하여 생성 시 한 번만 표시합니다. 재생성과 마찬가지로 이후에는 다시 표시되지 않으므로 즉시 복사하여 안전하게 보관하세요. 키의 권한을 직접 선택하거나 권한 집합에서 시딩할 수도 있습니다(아래 참조).

API Keys 페이지: 각 키의 이름, 부여된 권한, 생성 시간을 보여주는 카드, 재생성 및 비활성화 작업 포함; admin 같은 보호된 키는 별도로 표시됨

권장 키 구성

키	권한	사용처
`admin` (`ADMIN_KEY` 환경 변수를 통해 부트스트랩)	전체	운영/설정, 그리고 대시보드 컨테이너(`ADMIN_KEY`로 인증, 권한 검사를 통해 사용자 요청 프록시)
호스트별 수집기 키	`events:add`	각 에이전트 머신의 수집기
`dashboard-assistant` (`AGENT_API_KEY` 환경 변수를 통해 부트스트랩)	`events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run`	AI 어시스턴트 컨테이너, 자동으로 시딩됨, 보호됨; API를 통해 편집 불가
어시스턴트 텔레메트리 키 (선택 사항)	`events:add`	AI 어시스턴트 자체 계측(활성화된 경우)

어시스턴트 키. 어시스턴트 키는 서버가 AGENT_API_KEY 환경 변수에서 자동으로 시딩합니다(에이전트가 AGENTEYE_API_KEY로 제공하는 것과 동일한 시크릿). 수동 키 발급 단계나 admin 키가 필요하지 않습니다. 권한은 소스 코드에서 고정되어 있으므로 잘못된 구성으로 범위가 확장될 수 없습니다: 이벤트/평가/대시보드에 대한 읽기 접근, “AI에게 쿼리 작성 요청” 작성 플로우를 위한 dashboards-write 및 queries-read/write/run. 모든 SQL은 사용자가 작성한 쿼리와 동일한 읽기 전용 역할 및 sql_guard 검사를 거치므로, 이는 데이터 영역이 아닌 작성 영역을 확장합니다. 파괴적인 작업(queries:delete, dashboards:delete)은 의도적으로 어시스턴트 키에서 제외됩니다. admin 키와 마찬가지로 보호됩니다: keys API를 통해 비활성화하거나 재생성할 수 없으며, AGENT_API_KEY를 변경하고 재시작하는 방식으로만 교체할 수 있습니다. 대시보드 사용자는 어시스턴트를 보고 사용하기 위해 추가로 agent:use 권한이 필요합니다. 자체 계측을 활성화하는 경우 어시스턴트에게 별도의 events:add 전용 키를 부여하세요.

​권한

​이벤트 수집 및 조회

​세션 및 평가

​대시보드

​저장된 쿼리 (SQL 작성기)

​AI 어시스턴트

​API 키

​대시보드 사용자

​운영 설정

​알림 및 인시던트

​감사

​권한 집합

​부트스트랩 Admin 키

​조직 범위

​키 생성

​수집기 키 (수집 전용)

​대시보드 키 (읽기 전용)

​키 목록 조회

​키 비활성화

​키 재생성

​대시보드에서의 키 관리

​권장 키 구성

권한