스코프 (Scopes)
PAT는 <domain>:read, <domain>:write 형식의 scope로 접근 범위를 제한합니다. 토큰에는 필요한 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(?external_id= 룩업 포함), GET /contacts/{id}, GET /contacts/{id}/tags |
contact-tags:read | GET /contact-tags |
channel-tags:read | GET /channel-tags (상담 태그 카탈로그 — 연락처 태그와 별개 목록) |
channels:read | GET /channels(?tags=·?tag_match= 태그 필터 포함), 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가 필요합니다. :write scope는 같은 도메인의 :read scope를 포함하지 않으므로, 조회도 하려면 둘 다 부여하세요.
| Scope | 접근 가능 엔드포인트 |
|---|---|
messages:write | POST /channels/{id}/messages (답장 전송) |
channels:write | POST /channels/{id}/read·/close·/reopen·/assign (채널 조작), POST·DELETE /channels/{id}/tags (상담 태그 부여·해제), PUT /channels/{id}/consultation-memo (상담 메모 쓰기) |
contacts:write | POST /contacts, PATCH /contacts/{id}, POST·DELETE /contacts/{id}/tags, PUT /contacts/{id}/sms-consent (연락처 생성·수정·태그·SMS 동의) |
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 - 게시판 답변 변경 조회(
GET /board/answer-changes) —channels:read+messages:read
한쪽 scope만 가진 토큰으로 호출하면 403 INSUFFICIENT_SCOPE를 반환합니다.
scope가 부족할 때
403 INSUFFICIENT_SCOPE 응답의 error.details.required_scope에 토큰에 없는 scope가 들어 있습니다. 두 scope가 필요한 엔드포인트라면 빠진 것 중 첫 번째만 알려 주므로, 위 목록을 보고 필요한 scope를 한 번에 확인하세요.
토큰의 scope는 발급한 뒤에는 바꿀 수 없고, 회전해도 기존 scope를 그대로 이어받습니다. 필요한 scope를 넣어 새 토큰을 발급하고 호출하는 쪽의 토큰을 교체하세요. 이 오류도 요청 한도를 소비합니다.