인증 & 스코프

모든 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` · `knowledge.write`	위키 편집: 위키 문서 저장 · 가져오기. 삭제는 되돌릴 수 없어 늘 결재를 거칩니다. 결재를 받을 곳이 없는 직접 도구 호출(`/v1/tools`)에서는 삭제가 거부됩니다
`config.write`	업무 방식 편집: 스킬 · 표기·분류 기준 쓰기, 반복 업무 직접 호출. 만료(최대 1년)가 필수입니다
`a2a`	A2A 프로토콜 접속

2026-10-12 바뀜: 종전에는 wiki:write(knowledge.write) 하나로 스킬 · 표기·분류 기준 · 외부 MCP 서버 등록까지 할 수 있었습니다. 이제 위키 편집과 업무 방식 편집(config.write)이 나뉘고, 외부 MCP 서버 등록 · 연동 · 결재는 API 키로 할 수 없습니다. 키에는 발급하는 사람이 가진 권한까지만 줄 수 있고, 만료된 키는 401 API key expired 를 받습니다. 만료 14일 전에 매니저에게 알림이 갑니다.

스코프 함의

상위 스코프는 하위를 자동 포함합니다:

tools:write ⊃ tools:read
mcp ⊃ mcp:read, wiki:write
files: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(파일 다운로드 등)은 그 자체로 접근권한이므로 로그·공유에 주의하세요.

다음 단계

이전빠른 시작 다음 세션 & 대화 이어쓰기