> ## 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 Key가 조회하는 노트 범위

> 시스템 API Key와 시스템 Webhook은 워크스페이스 전체에 공유된 폴더의 노트만 조회하고 변경해요. 자격 증명 종류별 범위를 정리했어요.

시스템 API Key와 시스템 Webhook은 **워크스페이스 전체 구성원에게 공유된 폴더에 들어 있는 노트만** 다뤄요. 조회뿐 아니라 노트를 바꾸는 요청에도 같은 범위가 적용돼요. 구성원이 개인 폴더에 둔 노트, 일부 사람에게만 공유한 폴더의 노트, 어느 폴더에도 넣지 않은 노트는 이 범위에서 빠져요. 계정 API Key와 계정 Webhook은 사용자 신원과 실제 접근 권한을 따르므로 이 시스템 범위가 적용되지 않아요.

어느 폴더에도 넣지 않은 노트를 놓치기 쉬워요. 공유 대상이 정해지지 않은 상태라서 전체 공유 폴더의 노트로 보지 않아요.

## API Key 종류별로 어떤 노트를 다루나요?

| API Key 종류 | 다루는 노트 |
| - | - |
| **계정 API Key** | 그 사용자가 앱에서 볼 수 있는 노트와 같아요. 본인의 개인 폴더 노트도 포함해요. |
| **워크스페이스 API Key** | 그 워크스페이스에서 전체 구성원에게 공유된 폴더의 노트만 조회하고 변경해요. |
| **조직 API Key** | 조직에 소속된 워크스페이스에서, 그 워크스페이스 전체 구성원에게 공유된 폴더의 노트만 조회하고 변경해요. |
| **계정 Webhook** | 그 사용자가 현재 접근할 수 있는 모든 워크스페이스에서, 사용자가 접근할 수 있는 노트의 이벤트를 하나의 endpoint로 받아요. |
| **워크스페이스 Webhook** | 연결된 워크스페이스에서 전체 구성원에게 공유된 폴더의 노트 이벤트만 받아요. |
| **조직 Webhook** | 조직 소속 워크스페이스에서 전체 구성원에게 공유된 폴더의 노트 이벤트만 받아요. |

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

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

## 범위 밖의 노트는 어떻게 나타나나요?

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

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

연동에서 노트 수를 기준으로 동작을 판단한다면, 범위가 좁아졌을 때와 실제로 노트가 없을 때를 구분하지 못할 수 있어요.

## 폴더는 어디까지 다루나요?

시스템 API Key로 할 수 있는 폴더 작업은 **제목 수정, 이동, 순서 변경** 세 가지예요. 폴더 목록·단건 조회, 폴더 삭제, 노트를 폴더에 넣고 빼는 요청은 폴더 종류와 상관없이 계정 API Key만 할 수 있고, 시스템 API Key로 호출하면 `401`을 반환해요.

이 세 작업은 **전체 공유 폴더에만** 할 수 있어요. 개인 폴더나 일부 사람에게만 공유한 폴더를 대상으로 하면 `403`을 반환하고, 옮길 위치로 지정한 상위 폴더에도 같은 조건이 적용돼요. 순서 변경은 목록에 전체 공유 폴더가 아닌 폴더가 하나라도 있으면 요청 전체가 `403`이 되니, 전체 공유 폴더만 골라서 보내세요.

폴더를 옮겨도 공유 범위는 그대로예요. 상위 폴더의 공유 설정을 물려받는 옵션(`sharingTypeUpdateStrategy`)을 보내도 시스템 API Key에서는 적용되지 않아요.

**노트가 어느 폴더에 들어 있는지 조회할 때**(`GET /v1/external/notes/{guid}/folders`)는 전체 공유 폴더만 응답에 담겨요. 같은 노트가 구성원의 개인 폴더에도 들어 있다면 그 폴더는 빠져요. 이때는 에러가 나지 않고 목록만 짧아지므로, 폴더 이름으로 분류하는 연동이라면 계정 API Key로 볼 때와 결과가 다를 수 있어요.

노트를 검색할 때 `folderId`로 폴더를 지정하는 경우에도 전체 공유 폴더만 쓸 수 있어요. 개인 폴더의 ID를 지정하면 `404`를 반환해요.

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

**음성 파일 작업**(Voice File Job) API와 `voice_file_job.*` 이벤트(`created`, `completed`, `failed`, `deleted`)는 이 범위의 대상이 아니에요.

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

**계정 API Key를 발급해서 사용하세요.** 발급 방법은 [인증](/ko/developers/fundamentals/authentication)을 참고하세요.

연동에 필요한 노트를 전체 공유 폴더로 옮기는 방법도 있어요.

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

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

전환되면 조회 결과가 줄어드는 것뿐 아니라 **폴더 제목 수정·이동·순서 변경이 `403`으로 거부될 수 있어요.** 지금 그 요청이 성공하는 폴더라도 전체 공유 폴더가 아니면 전환 후에는 거부돼요.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.