> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tiro.ooo/llms.txt
> Use this file to discover all available pages before exploring further.

# 시스템 키가 조회하는 노트 범위

> 시스템 API 키와 Webhook은 워크스페이스 전체에 공유된 폴더의 노트만 조회해요. 키 종류별 조회 범위와 전환 중인 키를 정리했어요.

시스템 API 키와 Webhook은 **워크스페이스 전체 구성원에게 공유된 폴더에 들어 있는 노트만** 조회해요. 구성원이 개인 폴더에 둔 노트, 일부 사람에게만 공유한 폴더의 노트, 어느 폴더에도 넣지 않은 노트는 조회 범위에서 빠져요.

티로는 노트를 작성자의 것으로 보고, 관리자나 시스템이 개인 노트를 열람하지 않도록 설계해 왔어요. 앱에서는 이 기준이 이미 적용되어 있고, 시스템 자격으로 호출하는 API와 Webhook에도 같은 기준을 맞추고 있어요.

## 키 종류별로 어떤 노트를 조회하나요?

| 키 종류             | 조회하는 노트                                                                                |
| ---------------- | -------------------------------------------------------------------------------------- |
| **사용자 키**        | 그 사용자가 앱에서 볼 수 있는 노트와 같아요. 본인의 개인 폴더 노트도 포함해요.                                         |
| **워크스페이스 시스템 키** | 그 워크스페이스에서 전체 구성원에게 공유된 폴더의 노트만 조회해요.                                                  |
| **조직 시스템 키**     | 조직에 소속된 워크스페이스에서, 그 워크스페이스 전체 구성원에게 공유된 폴더의 노트만 조회해요.                                  |
| **Webhook**      | 노트 이벤트(`note.*`, `note_summary.*`, `note_document.*`)를 전체 구성원에게 공유된 폴더의 노트에 대해서만 발송해요. |

키 종류를 구분하는 방법과 발급 절차는 [인증](/ko/developers/fundamentals/authentication)에서 확인하세요.

## 어떤 노트가 조회되지 않나요?

시스템 키로는 아래 노트를 조회할 수 없어요.

* 구성원의 **개인 폴더**에 있는 노트
* **일부 구성원에게만 공유한 폴더**의 노트
* **어느 폴더에도 들어 있지 않은** 노트

세 번째 경우를 놓치기 쉬워요. 폴더에 넣지 않은 노트는 공유 대상이 정해지지 않은 상태라서, 전체 공유 폴더에 있는 노트로 보지 않아요.

<Warning>
  **Scope를 넓혀도 조회 범위는 달라지지 않아요.** Scope는 키가 호출할 수 있는 API를 정하고, 이 문서의 조회 범위는 그 API가 어떤 노트를 돌려주는지를 정해요. `note:read`를 가진 시스템 키도 전체 공유 폴더 밖의 노트는 조회하지 못해요. 관리자가 발급한 키도 같아요.
</Warning>

## 조회되지 않는 노트는 어떻게 나타나나요?

호출하는 API에 따라 다르게 나타나요.

| 호출                              | 결과                                     |
| ------------------------------- | -------------------------------------- |
| 목록, 검색                          | 조회 범위 밖의 노트가 **응답에서 빠져요.** 에러는 나지 않아요. |
| 노트 단건 조회                        | `404`를 반환해요.                           |
| 노트의 전사, 요약, 문서, 공유 링크, 소속 폴더 조회 | `404`를 반환해요.                           |

<Note>
  조회 범위 밖의 노트는 `403`이 아니라 `404`를 반환해요. 노트가 존재하는지 자체를 알리지 않기 위한 동작이에요. 그래서 **삭제된 노트와 응답이 같아요.** 어제까지 조회되던 노트가 `404`를 반환하기 시작했다면 그 노트가 전체 공유 폴더 밖으로 이동했는지 먼저 확인하세요.
</Note>

목록과 검색은 에러 없이 결과만 줄어들어요. 연동에서 노트 수를 기준으로 동작을 판단한다면, 조회 범위가 좁아졌을 때와 실제로 노트가 없을 때를 구분하지 못할 수 있어요.

워크스페이스의 폴더 목록 자체는 시스템 키로 조회할 수 없어요. `GET /v1/external/workspaces/{workspaceGuid}/folders`는 사용자 키를 요구하고, 시스템 키로 호출하면 `401`을 반환해요.

## 이 범위가 적용되지 않는 API는 무엇인가요?

노트 본문 조회가 아닌 아래 항목은 이 범위의 대상이 아니에요.

* **폴더 이벤트**(`folder.note.*`) Webhook
* **음성 파일 작업**(Voice File Job) API와 이벤트

## 개인 폴더의 노트가 필요하면

**사용자 키를 발급해서 사용하세요.** 사용자 키는 그 사용자가 앱에서 볼 수 있는 노트를 조회하므로, 본인의 개인 폴더 노트도 가져올 수 있어요. 발급 방법은 [인증](/ko/developers/fundamentals/authentication)을 참고하세요.

연동에 필요한 노트를 전체 공유 폴더로 옮기는 방법도 있어요. 이 경우 그 노트는 워크스페이스 구성원 모두에게 보이게 되니, 옮기기 전에 공유해도 되는 내용인지 확인하세요.

## 기존에 발급한 키는 어떻게 되나요?

이 범위가 적용되기 전에 발급한 시스템 키와 등록한 Webhook은 당분간 예전처럼 동작하고, 차례로 전환될 예정이에요. 그래서 지금 새로 발급한 키가 기존 키보다 노트를 더 적게 반환할 수 있는데 정상이에요. 전환이 끝나면 모든 시스템 키와 Webhook이 이 문서의 범위를 따라요.

전환 대상인 키와 Webhook은 [Tiro Platform](https://platform.tiro.ooo)의 API Keys, Webhooks 화면에서 확인해보세요.