인증 & 스코프
모든 API 호출은 발급받은 API 키로 인증합니다.
인증 헤더
Authorization: Bearer dai_live_…
키는 웹앱 설정 > 개발자 도구에서 발급하며, 발급 시 한 번만 원문이 표시됩니다(서버엔 해시로만 저장 — 분실 시 재발급). 워크스페이스(직원)마다 별도로 발급합니다.
스코프 (권한)
키에는 필요한 스코프만 부여하세요(최소 권한 원칙). 미보유 스코프로 접근하면 403이 반환됩니다.
| 스코프 | 허용 범위 |
|---|---|
chat | 메시지 전송 / 명령 실행 |
sessions:read | 세션·대화 이력 조회 |
tools:read | 읽기 전용 도구 호출 (파일 다운로드 포함) |
tools:write | 상태 변경 도구 호출 (tools:read 포함) |
files:write | 인바운드 업로드 티켓 발급 |
files:write:unrestricted | 첨부를 deny-list로 처리(임의 형식 허용, files:write 포함) |
secret | 시크릿 제출(headless secret) |
mcp | MCP 서버 접속 (mcp:read·wiki:write 포함) |
mcp:read | MCP 읽기 전용 |
wiki:write | 위키(공용 지식창고) 저장 |
a2a | A2A 프로토콜 접속 |
스코프 함의
상위 스코프는 하위를 자동 포함합니다:
tools:write⊃tools:readmcp⊃mcp:read,wiki:writefiles:write:unrestricted⊃files:write
예: tools:write 키는 tools:read가 필요한 파일 다운로드도 됩니다.
엔드포인트별 필요 스코프
| 엔드포인트 | 스코프 |
|---|---|
POST /messages | chat |
GET /sessions, GET /sessions/:id/messages, GET /sessions/:id/events | sessions:read |
POST /files (업로드 티켓) | files:write |
POST /files/download | tools:read |
POST /approvals/:id/secret | secret |
POST /mcp | mcp |
POST /a2a | a2a |
보안 권장
- 키는 서버 환경변수/시크릿 매니저에 두고 클라이언트(브라우저)에 노출하지 마세요.
- 용도별로 키를 분리하고, 유출 시 즉시 재발급하세요.
- 발급된 signed URL(파일 다운로드 등)은 그 자체로 접근권한이므로 로그·공유에 주의하세요.