시작하기
프로젝트 키와 관리 API 키의 차이, scope, IP 제한, secret 보관 방법을 설명합니다.
종류 | 범위 | 주요 용도 |
|---|---|---|
프로젝트 키 | 하나의 프로젝트 | 이벤트와 피드백 ingest, 프로젝트 서버 |
관리 API 키 | 조직 전체 | Projects, Monitors, Status Page, Feedback, Servers REST API |
프로젝트 키는 ingest 계열이고 project_id로 프로젝트에 연결됩니다. 관리 API 키는 조직 계열이며 조직 전체를 대상으로 합니다.
Scope | 한국어 표시 | 용도 |
|---|---|---|
| 상태 읽기 | 상태 데이터 조회 |
| 상태 쓰기 | 상태 이벤트 전송 |
| 피드백 읽기 | 피드백 조회 |
| 피드백 쓰기 | 피드백 전송 |
| Analytics 쓰기(레거시) | 레거시 분석 이벤트 |
| 에러 쓰기 | 서버 에러 수집·소스맵 업로드 |
| 관리 읽기 | 관리 리소스 조회 |
| 관리 쓰기 | 관리 리소스 변경 |
| 서버 읽기 | 서버 목록과 상세 조회 |
| 서버 쓰기 | 서버 등록, 수정, 삭제, 토큰 재발급 |
| 문서 읽기 | 문서 사이트와 페이지 조회 |
| 문서 쓰기 | 문서 사이트 작성과 게시 |
필요한 최소 scope만 선택하세요. admin:read와 admin:write는 서버 API에서도 각각 읽기와 쓰기 권한을 부여합니다.
문서 사이트 API와 MCP는 조직 키 전용입니다. docs:read와 docs:write는 admin:read와 admin:write로도 사용할 수 있습니다.
errors:write는 새 프로젝트 키에 적용됩니다. 기존 키에는 자동으로 추가되지 않으므로 새 키를 발급하거나, scope 편집이 활성화된 경우 키를 편집하세요.
secret은 발급 직후 한 번만 표시됩니다. 안전한 secret manager나 mode-600 파일에 저장하고 로그, 저장소, 채팅에 출력하지 마세요. 키를 잃어버리면 기존 secret을 다시 조회할 수 없으므로 새 키를 발급해야 합니다.
관리 API 요청은 다음 형식의 헤더를 사용합니다.
Authorization: Bearer <keyId>.<secret>MCP 클라이언트(opencode·Claude Code 등)에서도 같은 키를 사용합니다. 설정 방법은 MCP를 참고하세요.
키마다 CIDR 형식의 IP allowlist를 설정할 수 있습니다. 허용 목록 밖의 요청은 403 ip_not_allowed입니다.
사용하지 않는 키는 API 키 화면에서 폐기하세요. 폐기한 키는 즉시 인증에 실패합니다.
이 페이지가 도움이 되었나요?