API Keys

​

대부분의 배포 환경에서 필요한 3가지 키

​

권한

참고: 사람/대시보드 전용으로 유효하여 API key에는 부여할 수 없는 권한이 두 가지 있습니다: orgs:admin(인스턴스 관리, 운영자 전용)과 keys:update. 이 두 권한 중 하나를 부여하려는 POST /keys 또는 PATCH /keys/:id 요청은 HTTP 422로 거부됩니다. bearer 키가 키를 생성할 수 있지만 편집은 불가능한 이유에 대해서는 아래 keys:update 항목을 참조하세요.

​

이벤트 수집 및 조회

​

세션 및 평가

​

대시보드

​

저장된 쿼리 (SQL 컴포저)

​

AI 어시스턴트

​

API Keys

​

대시보드 사용자

​

운영 설정

​

알림 및 인시던트

​

감사

참고: 키에 감사 기능을 부여하려면 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는 유효한 키가 필요하지만 특정 권한은 불필요하므로, 로그인한 모든 사용자가 액세스 변경에 대해 문의할 관리자를 확인할 수 있습니다.

​

권한 집합

• DEFAULT_USER_PERMISSIONS(관리자가 + 새 사용자를 열 때 미리 선택된 권한)는 기본적으로 standard 집합으로 설정됩니다.
• agenteye-orgctl의 --set 플래그(운영자 멤버 관리)는 명명된 집합에서 멤버를 시작하며, 이후 --add / --remove로 세부 조정할 수 있습니다.

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

​

부트스트랩 관리자 키

​

조직 스코핑

​

키 생성

​

컬렉터 키 (수집 전용)

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

{
  "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"

​

키 비활성화

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"

​

대시보드의 키 관리

​

권장 키 구성

참고: 어시스턴트 키는 서버가 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 keys는 확장되지 않았습니다. 감사 기능이 필요한 키에는 audits:*를 명시적으로 부여하세요.

레거시 alerts:ack 토큰의 저장된 권한 부여는 incidents:ack로 파싱되어, 온콜 담당자가 키 재발행 없이 액세스를 유지합니다. 이 토큰은 더 이상 대시보드 사용자 편집기에서 할당할 수 없으며, 대신 incidents:ack가 제공됩니다.

​

다음 단계

• Python SDK: 에이전트 코드가 이벤트를 전송할 때 인증하는 방법.
• Security: 로그인, 액세스 제어, per-organization 데이터 격리 작동 방식.