키 스코프
스코프는 키가 호출할 수 있는 API 영역을 나타내요. API 레퍼런스의 모든 엔드포인트에는 필요한 스코프
하나가 명시되어 있어요. 그 스코프가 없는 키로 보낸 요청은 무엇이든 읽거나 바꾸기 전에 403 상태와
api_keys.scope 코드로 거부돼요.
스코프는 키가 호출할 수 있는 오퍼레이션을 정해요. 그 오퍼레이션이 어떤 객체를 보는지는 여전히 키의 역할, 데이터 프로필,
컬렉션이 정해요. cards:write 스코프가 있어도 viewer 역할의 키는 카드를 바꿀 수 없고, 컬렉션 하나로 제한된 키는 다른
컬렉션을 볼 수 없어요.
스코프
| 스코프 | 허용하는 일 |
|---|---|
cards:read | 카드, 컬렉션, 폴더 읽기. |
cards:write | 카드, 컬렉션, 폴더의 생성, 변경, 삭제. |
search | 지식 베이스 검색(POST /v1/search). |
ask | 어시스턴트에게 질문하기(POST /v1/ask, POST /v1/chat). |
import:write | 조직의 사용자 지정 소스에 쓰기(동기화, 배치, 삭제)와 그 상태 읽기. 소스와 소스 키를 만들려면 admin이 필요해요. |
webhooks:manage | 웹훅 관리와 이벤트 피드 읽기(GET /v1/webhook-events). 둘 다 admin 역할도 필요해요. |
users:read | 사용자와 그룹 읽기. |
users:write | 사용자와 그룹 변경. |
analytics:read | 분석 데이터 읽기. |
audit:read | 감사 로그 읽기. |
finance:read | 재무 보고서, 청구서, 결제 읽기. |
catalog:read | 서비스 카탈로그 읽기. |
files:read | 내보낸 답변처럼 생성된 파일 읽기. |
files:write | 생성된 파일의 변경과 삭제. |
permissions:manage | 객체에 대한 권한 부여와 회수. |
admin | 조직의 설정과 조직의 API 키. admin 스코프가 있는 키에는 다른 모든 스코프도 있어요. |
검색과 질문은 의미상 읽기예요. 읽기만 할 수 있는 키로도 검색하고 질문할 수 있어요.
스코프 고르기
연동 시스템이 쓰는 스코프만 부여하고 그 밖의 스코프는 주지 마세요.
| 연동 시스템 | 스코프 |
|---|---|
| 채팅 도구의 Q&A 봇 | search, ask |
| 문서 시스템에서 가져오기 | cards:write(카드 API) 또는 import:write(사용자 지정 소스) |
| 데이터 웨어하우스로 내보내기 | cards:read, users:read, 이벤트 피드용 webhooks:manage |
| HR 시스템에서 사용자 프로비저닝 | users:write |
키를 만들 때 목록을 보내세요.
curl -X POST https://api.sursa.com/v1/api-keys \
-H "Authorization: Bearer $SURSA_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Support bot", "role": "viewer", "scopes": ["search", "ask"]}'이전 스코프
스코프가 세분화되기 전에 만든 키도 계속 동작해요. 그 키의 read, write, admin 스코프는 다음 묶음에 해당해요.
| 이전 스코프 | 의미 |
|---|---|
read | cards:read, search, ask, users:read, analytics:read, finance:read, catalog:read, files:read |
write | read의 모든 스코프와 cards:write, files:write, users:write, permissions:manage |
admin | 모든 스코프 |
스코프를 명시하지 않고 만든 키는 역할에서 스코프를 받아요. admin은 admin, editor와 verifier는 write,
viewer는 read 스코프를 받아요.
키의 스코프 확인하기
GET /v1/me는 키에 어떤 스코프가 있든 요청을 보낸 키의 스코프를 반환해요. 스코프를
명시하지 않고 만든 키라면 read, write처럼 역할에 따른 이전 스코프가 반환되며, 각각이 무엇을 뜻하는지는 위 표에
나와 있어요. 오퍼레이션이 api_keys.scope 오류로 실패하면 error.message에 빠진 스코프가 나와요.