스코프 (Scopes)
PAT는 <domain>:read / <domain>:write 형식의 fine-grained scope로 접근 범위를 제한합니다. 토큰에는 필요한 scope만 부여하는 것을 권장합니다.
스코프 목록
| Scope | 접근 가능 엔드포인트 |
|---|---|
workspaces:read | GET /workspace |
members:read | GET /members, GET /members/{id} |
teams:read | GET /teams, GET /teams/{id}/members |
contacts:read | GET /contacts, GET /contacts/{id}, GET /contacts/{id}/tags |
contact-tags:read | GET /contact-tags |
channels:read | GET /channels, GET /channels/{id} |
messages:read | GET /channels/{id}/messages (channels:read와 함께 필요), GET /messages/{id} |
attachments:read | GET /attachments/{id} (messages:read와 함께 필요) |
macros:read | GET /macros |
hours:read | GET /hours |
integrations:read | GET /integrations |
campaigns:read | GET /campaigns, GET /campaigns/{id} |
tasks:read | GET /tasks, GET /tasks/{id} |
search:read | GET /search |
inbound-webhook-configs:read | GET /inbound-webhook-configs |
workflows:read | GET /workflows |
ai-agents:read | GET /ai-agents |
voice:read | GET /voice/calls |
쓰기 스코프
상담 콘솔처럼 메시지를 보내고 채널을 조작하거나, PAT로 직접 outbound 웹훅을 등록하려면 아래 :write scope가 필요합니다.
| Scope | 접근 가능 엔드포인트 |
|---|---|
messages:write | POST /channels/{id}/messages (답장 전송) |
channels:write | POST /channels/{id}/read·/close·/reopen·/assign (채널 조작) |
webhooks:read | GET /outbound-webhooks, GET /outbound-webhooks/{id}, GET /outbound-webhooks/{id}/delivery-logs |
webhooks:write | POST·PATCH·DELETE /outbound-webhooks 및 /regenerate-secret·/toggle |
쓰기 엔드포인트의 상세 규약은 메시징 쓰기 API와 Outbound 웹훅 관리 API를 참고하세요.
workspaces:read 자동 포함
모든 토큰에는 workspaces:read가 발급 시 자동으로 포함됩니다. 선택한 scope와 무관하게 항상 부여되므로, 워크스페이스 메타 조회(GET /workspace)는 별도 선택 없이 가능합니다.
복합 scope 규칙
일부 엔드포인트는 두 scope를 모두 요구합니다.
- 채널 메시지 목록(
GET /channels/{id}/messages) —channels:read+messages:read - 첨부 다운로드(
GET /attachments/{id}) —attachments:read+messages:read
한쪽 scope만 가진 토큰으로 호출하면 403 INSUFFICIENT_SCOPE가 반환됩니다.