시스템 API 키와 Webhook은 워크스페이스 전체 구성원에게 공유된 폴더에 들어 있는 노트만 조회해요. 구성원이 개인 폴더에 둔 노트, 일부 사람에게만 공유한 폴더의 노트, 어느 폴더에도 넣지 않은 노트는 조회 범위에서 빠져요.
티로는 노트를 작성자의 것으로 보고, 관리자나 시스템이 개인 노트를 열람하지 않도록 설계해 왔어요. 앱에서는 이 기준이 이미 적용되어 있고, 시스템 자격으로 호출하는 API와 Webhook에도 같은 기준을 맞추고 있어요.
키 종류별로 어떤 노트를 조회하나요?
키 종류를 구분하는 방법과 발급 절차는 인증에서 확인하세요.
어떤 노트가 조회되지 않나요?
시스템 키로는 아래 노트를 조회할 수 없어요.
- 구성원의 개인 폴더에 있는 노트
- 일부 구성원에게만 공유한 폴더의 노트
- 어느 폴더에도 들어 있지 않은 노트
세 번째 경우를 놓치기 쉬워요. 폴더에 넣지 않은 노트는 공유 대상이 정해지지 않은 상태라서, 전체 공유 폴더에 있는 노트로 보지 않아요.
Scope를 넓혀도 조회 범위는 달라지지 않아요. Scope는 키가 호출할 수 있는 API를 정하고, 이 문서의 조회 범위는 그 API가 어떤 노트를 돌려주는지를 정해요. note:read를 가진 시스템 키도 전체 공유 폴더 밖의 노트는 조회하지 못해요. 관리자가 발급한 키도 같아요.
조회되지 않는 노트는 어떻게 나타나나요?
호출하는 API에 따라 다르게 나타나요.
조회 범위 밖의 노트는 403이 아니라 404를 반환해요. 노트가 존재하는지 자체를 알리지 않기 위한 동작이에요. 그래서 삭제된 노트와 응답이 같아요. 어제까지 조회되던 노트가 404를 반환하기 시작했다면 그 노트가 전체 공유 폴더 밖으로 이동했는지 먼저 확인하세요.
GET /v1/external/workspaces/{workspaceGuid}/folders는 사용자 키를 요구하고, 시스템 키로 호출하면 401을 반환해요.
이 범위가 적용되지 않는 API는 무엇인가요?
노트 본문 조회가 아닌 아래 항목은 이 범위의 대상이 아니에요.
- 폴더 이벤트(
folder.note.*) Webhook
- 음성 파일 작업(Voice File Job) API와 이벤트
개인 폴더의 노트가 필요하면
사용자 키를 발급해서 사용하세요. 사용자 키는 그 사용자가 앱에서 볼 수 있는 노트를 조회하므로, 본인의 개인 폴더 노트도 가져올 수 있어요. 발급 방법은 인증을 참고하세요.
연동에 필요한 노트를 전체 공유 폴더로 옮기는 방법도 있어요. 이 경우 그 노트는 워크스페이스 구성원 모두에게 보이게 되니, 옮기기 전에 공유해도 되는 내용인지 확인하세요.
기존에 발급한 키는 어떻게 되나요?
이 범위가 적용되기 전에 발급한 시스템 키와 등록한 Webhook은 당분간 예전처럼 동작하고, 차례로 전환될 예정이에요. 그래서 지금 새로 발급한 키가 기존 키보다 노트를 더 적게 반환할 수 있는데 정상이에요. 전환이 끝나면 모든 시스템 키와 Webhook이 이 문서의 범위를 따라요.
전환 대상인 키와 Webhook은 Tiro Platform의 API Keys, Webhooks 화면에서 확인해보세요. 
