/
API 키와 AI 연결에 쓰이는 스코프 15개: 각 스코프가 허용하는 것, 대시보드에서의 이름, 어떤 API 키로도 할 수 없는 것을 정리했습니다.
스코프는 API 키가 할 수 있는 일을 정합니다. MCP로 연결하는 AI 어시스턴트에도 같은 스코프 15개가 적용됩니다. 항상 애플리케이션에 정말 필요한 스코프만 고르세요.
기본 규칙
- 모든 엔드포인트는 정확히 하나의 스코프를 요구함
- API 키에서는 write:X에 read:X가 자동으로 포함됨. 대시보드에도 “write:X는 read:X를 자동으로 포함합니다”라고 표시됨
- 스코프가 없으면 API가 403 insufficient_scope로 응답하고 필요한 스코프를 details.required_scope에 알려 줌
- API 키에 아예 허용되지 않은 엔드포인트도 403 insufficient_scope로 응답함
- 멤버, 결제, 도메인 관리 같은 소유자와 관리자 기능은 어떤 스코프로도 접근할 수 없음
모든 스코프
“새 API 키 만들기” 대화상자에서는 영역마다 “읽기” 또는 “쓰기”를 고르며, 키 목록에는 첫 번째 열의 스코프 이름이 표시됩니다. “읽기 · 페이지” 형태는 AI 앱의 동의 페이지와 “연결된 앱”에 나타납니다.
| 스코프 | AI 앱에서 | 허용하는 것 |
|---|---|---|
| read:pages | 읽기 · 페이지 | 페이지 나열과 읽기, 초안 읽기와 검증, 블록 나열, SEO 읽기, 버전 나열, 블록 종류 가져오기 |
| write:pages | 쓰기 · 페이지 | 페이지 만들기와 편집(핸들 포함), 초안 편집, 블록 만들기·편집·삭제·순서 변경, SEO 편집, 공개 범위, 게시, 버전 복원, 비공개 페이지 초대 링크 |
| read:links | 읽기 · 링크 | 페이지의 링크 나열과 읽기 |
| write:links | 쓰기 · 링크 | 링크 만들기, 편집, 삭제, 순서 변경 |
| read:assets | 읽기 · 에셋 | 에셋 나열 |
| write:assets | 쓰기 · 에셋 | 에셋 업로드와 삭제, 페이지용 업로드 |
| read:forms | 읽기 · 폼 | 폼 읽기, 요약, 제출 내역 나열과 CSV 내보내기(내보내기는 Creator Pro부터) |
| write:forms | 쓰기 · 폼 | 폼 만들기, 편집, 삭제 |
| read:stats | 읽기 · 통계 | 페이지와 워크스페이스 통계(요약, 시계열, 비교, 링크, 위젯, 전환, 인기 페이지), 푸시 기록과 푸시 사용량 |
| read:workspaces | 읽기 · 워크스페이스 | 플랜 기능, 사용량, 멤버 목록, 워크스페이스 설정 읽기, 도메인 나열, 템플릿 나열과 읽기, 콜백 시크릿 나열과 읽기(평문 시크릿 제외) |
| write:workspaces | 쓰기 · 워크스페이스 | 현재 read:workspaces 외의 엔드포인트 없음 |
| read:donations | 읽기 · 후원 결제 | 워크스페이스의 후원 결제(‘후원하기’ 블록을 통한 결제) 합계 |
| read:short_links | 읽기 · 단축 링크 | 단축 링크 나열과 읽기 |
| write:short_links | 쓰기 · 단축 링크 | 단축 링크 만들기, 편집, 삭제 |
| write:templates | 쓰기 · 워크스페이스 템플릿 | 자체 워크스페이스 템플릿 만들기, 편집, 삭제(읽기는 read:workspaces로). 커스텀 템플릿 참고 |
어떤 엔드포인트가 어떤 스코프에 속하는지는 영역별 API 엔드포인트에서 정확히 볼 수 있습니다.
어떤 API 키로도 할 수 없는 것
- 페이지 삭제
- 초안 미리보기 링크 만들기
- 기기, 국가, 유입 경로, UTM별 통계 세부 분석
- 푸시 알림 보내기와 푸시 규칙 관리
- 연동 연결 또는 해제
- 웹훅 관리
- 도메인 추가, 인증, 활성화, 비활성화, 삭제
- 멤버, 초대, 역할 관리와 소유권 이전
- 워크스페이스 설정과 결제 변경
- 콜백 시크릿 만들기, 편집, 교체, 삭제
- 후원 결제 목록, 데이터 열람 요청, 폼 제출 내역 익명화
- 프로필, 팔로우하는 페이지, API 키 자체의 관리
이런 일은 대시보드에서 합니다.
AI 어시스턴트의 스코프
MCP 연결에서는 동의 페이지에서 같은 스코프를 고릅니다. 차이점은 두 가지입니다. 첫째, 그곳에서는 쓰기 권한에 읽기 권한이 포함되지 않으므로 둘 다 허용하세요. 둘째, 역할이 선택을 제한합니다. 뷰어는 읽기 권한만(폼과 단축 링크 제외), 편집자는 “쓰기 · 워크스페이스”, 단축 링크, 워크스페이스 템플릿을 제외한 모든 권한을 받습니다. 자세한 내용은 권한, 보안, 한도에 있습니다.
권장 조합
| 용도 | 스코프 |
|---|---|
| 보고서와 대시보드 | read:stats, read:pages |
| CMS나 쇼핑몰에서 링크 동기화 | write:links, read:pages |
| 페이지 자동 관리와 게시 | write:pages, write:links |
| CRM의 캠페인 링크 | write:short_links |
| 폼의 리드를 CRM으로 전달 | read:forms |
| CI 파이프라인에서 템플릿 배포 | write:templates, read:workspaces |
함께 보면 좋은 글
원하는 내용을 찾지 못했나요?
필요한 내용을 알려 주시면 지원팀이 직접 도와드립니다.