[Notion API][OAuth] 설치 토큰으로 page와 database를 같이 쓸 때 공유 범위를 어디까지 나눠야 하나

IT 리서치 노트

[Notion API][OAuth] 설치 토큰으로 page와 database를 같이 쓸 때 공유 범위를 어디까지 나눠야 하나

Notion OAuth 앱에서 설치 토큰으로 page와 database를 같이 다루기 시작하면 page picker에서 한두 개만 고르게 해도 될 것처럼 보이지만, 실제로는 source database와 relation 대상 database 범위까지 생각해야 한다. 2026년 7월 3일 기준 Notion 공식 문서를 다시 보면 public connection은 사용자가 page picker로 범위를 정하고, 공유되지 않은 database query는 404, capability 부족은 403으로 갈리며, linked database는 원본 source database를 따로 공유해야 한다. 이 글은 page와 database를 같이 쓰는 앱에서 공유 범위를 어디까지 나눠 설계해야 하는지 정리한 것이다.

목차

1. 개요
2. 어디서 실제로 막히는가
3. 실무에서 적용하는 순서
4. 공식 문서와 예시 화면으로 확인하기
5. 주의사항과 리스크
6. 결론
7. 참고 링크

1. 개요

결론부터 말하면 Notion OAuth 설치 토큰은 'page 하나를 고르면 관련 database도 다 보인다'는 식으로 설계하면 안 된다. 부모 page, source database, relation 대상 database, 그리고 endpoint capability를 따로 생각해야 한다. page와 database를 함께 쓰는 앱일수록 공유 범위 표를 먼저 만드는 편이 설치 실패를 크게 줄인다.

이미 403과 404를 실제 응답 기준으로 나누는 글이 런타임 진단을 다뤘다면, 이번 글은 그 오류를 아예 설계 단계에서 줄이는 쪽에 가깝다. 또 internal connection과 public OAuth를 나누는 글을 봤다면, 여기서는 public connection 설치 범위를 더 세밀하게 쪼개는 셈이다.

page와 database 범위를 나눈 뒤에도 relation 컬럼만 비어 보인다면 relation 속성이 비어 보일 때 source database 공유 범위를 어디까지 열어야 하는지 정리한 글로 이어서 보는 편이 순서가 맞다.

2. 어디서 실제로 막히는가

실무에서 자주 생기는 오해는 세 가지다. 첫째, OAuth page picker에서 한 parent page만 고르면 그 안의 linked database와 related database까지 다 읽힐 것이라고 본다. 둘째, 404가 나면 항상 잘못된 ID라고 생각하고 공유 범위 문제를 놓친다. 셋째, capability 부족 403과 resource 미공유 404를 같은 설치 가이드로 처리한다.

Notion 문서는 public connection이 OAuth 과정에서 사용자가 고른 page 범위 안에서 동작한다고 설명한다. Query database 문서는 database가 공유되지 않으면 404, read content capability가 없으면 403이 난다고 구분한다. Retrieve a database와 working with databases guide는 linked database를 직접 지원하지 않으므로 원본 source database를 공유해야 한다고 재차 적는다. 이 세 문서를 같이 읽으면 공유 범위는 page 하나가 아니라 리소스 종류별 목록이라는 점이 드러난다.

여기에 relation property가 들어가면 한 단계 더 복잡해진다. database 자체는 공유됐어도 relation 대상 database가 안 공유되면 속성이 일부 빠질 수 있다. 그러니 설치 토큰으로 page와 database를 같이 쓰는 기능은 사용자가 어떤 page를 선택하고, 어떤 source database를 추가로 공유하고, relation 대상 database까지 어디서 연결해야 하는지 UI 문구와 help 문서에서 먼저 분리해 줘야 한다.

• 증상: page는 읽히는데 database query가 404로 실패한다.
• 실패: linked database가 보이니 source database 공유는 필요 없다고 본다.
• 막힘: capability 403과 미공유 404를 같은 문제로 취급한다.
• 누락: relation 대상 database 범위를 설치 가이드에 적지 않는다.

상황	먼저 볼 곳	판단 기준
page는 보이는데 DB query가 안 된다	database 공유 여부	404라면 미공유일 가능성을 먼저 본다
linked DB만 고르게 했다	source database 위치	원본 source까지 공유해야 한다
일부 relation 속성이 비어 있다	related database 공유 여부	relation 대상 DB도 범위에 넣는다

3. 실무에서 적용하는 순서

가장 실용적인 설계 순서는 다섯 단계다. 먼저 앱이 접근하는 리소스를 부모 page, source database, related database로 나눈다. 두 번째로 endpoint별 capability를 체크한다. 세 번째로 OAuth 설치 문구에 page picker에서 최소 무엇을 선택하고 어떤 database를 추가로 공유해야 하는지 적는다. 네 번째로 linked database가 보이면 source database를 찾아 열고, Add connections로 공유하고, relation 대상 database도 같은 방식으로 연결하라고 안내한다. 마지막으로 설치 직후에는 database query를 실행하고 retrieve database로 schema를 읽고 page update를 한 번 시도해 403과 404를 다른 도움말 경로로 보낸다.

1. 리소스를 page, source database, related database로 나눈다.
2. endpoint capability를 리소스와 별도로 체크한다.
3. page picker에서 최소 선택 범위를 안내 문구에 적는다.
4. linked database면 source database 공유도 요구한다.
5. 설치 직후 403과 404를 다른 도움말로 분기한다.

핵심은 OAuth 설치를 '토큰 발급'이 아니라 '권한 범위 설계'로 보는 것이다. 사용자는 page picker에서 page를 선택하고, 관리자는 source database를 공유하고, 앱은 query와 retrieve를 실제로 실행해 설치 직후 범위를 검증해야 한다. Notion 문서가 page picker, capability, linked database source 규칙을 각각 따로 적는 이유도 이 범위들이 서로 대체되지 않기 때문이다.

설치 가이드 메모 예시

1. 부모 page를 page picker에서 선택
2. source database가 linked view라면 원본 database도 공유
3. relation을 읽는 경우 관련 database도 공유
4. read content capability가 켜져 있는지 확인
5. 404면 공유 범위, 403이면 capability를 먼저 점검

설치 직후 실무 점검도 고정해 두는 편이 좋다. 사용자는 page picker에서 부모 page를 선택하고, 관리자는 source database를 열어 Add connections 메뉴를 클릭하고, database ID를 복사하고, query를 실행하고, retrieve 응답을 확인하고, relation database도 같은 방식으로 조회한다. 이어서 capability 설정을 확인하고, page update 응답과 오류 로그를 저장하고, 콘솔에서 403인지 404인지 다시 확인하면 설치 실패를 훨씬 빨리 줄일 수 있다.

이렇게 정리해 두면 설치 직후 오류가 나도 어디를 다시 고르게 해야 하는지 사용자에게 바로 안내할 수 있다. 특히 database query와 page update를 같이 제공하는 SaaS라면 onboarding 성공률 차이가 크게 난다.

4. 공식 문서와 예시 화면으로 확인하기

첫 자료는 public connection OAuth 흐름의 page picker 설명이다. Notion은 사용자가 OAuth 과정에서 어떤 페이지를 연결에 줄지 직접 선택한다고 적는다.

public connection의 설치 토큰은 사용자가 page picker에서 고른 페이지 범위 안에서만 움직인다.

즉 설치 토큰 하나를 받았다고 workspace 전체 page와 database가 자동으로 열리는 구조가 아니다. 공유 범위 설계는 OAuth 승인의 일부다.

두 번째 화면은 authorization guide의 기본 규칙이다. 페이지가 연결에 공유되지 않으면 API 요청이 에러로 응답한다고 못 박는다.

공유되지 않은 page는 installation token이 있어도 요청이 실패한다.

이 규칙은 database에도 그대로 이어진다. page와 database를 같이 읽는 기능이라면 어떤 부모 page를 고르게 할지, 어떤 원본 database를 꼭 포함시켜야 할지 미리 설계해야 한다.

세 번째 자료는 Query database 문서의 permission 설명이다. 공유되지 않은 database를 query하면 404가 난다고 적고, capability가 없으면 403이 난다고도 구분한다.

Notion은 database 미공유는 404, read content capability 부족은 403으로 나눠 설명한다.

이 차이 때문에 공유 범위 설계는 endpoint capability와 page picker 범위를 동시에 봐야 한다. 설치 토큰이 있다고 해서 resource 접근과 capability가 같이 해결되는 것은 아니다.

네 번째 화면은 Retrieve a database 문서의 linked database 주의점이다. Notion API는 linked database를 직접 지원하지 않고 원본 source database를 공유하라고 설명한다.

linked database를 쓰더라도 API에는 원본 source database 공유가 필요하다.

그래서 page 하나만 picker에서 고르게 해 두고 linked database가 있으니 괜찮겠지라고 생각하면 실패한다. source database와 relation 대상 database까지 어디까지 줄지 따로 정해야 한다.

다섯 번째 자료는 working with databases guide의 linked data source 설명이다. 원본 data source가 있는 database를 공유하라고 다시 강조한다.

linked view가 아니라 original data source를 공유해야 API가 기대대로 동작한다.

page와 database를 같이 다루는 OAuth 앱이라면 page picker UX만 볼 것이 아니라 '사용자가 어떤 원본 database까지 선택해야 하는가'를 안내 문구에 넣어 두는 편이 낫다.

공유 범위를 설계할 때는 page, source database, relation 대상 database를 따로 적는 표가 실용적이다. 한 칸에 몰아 넣으면 어느 범위가 빠졌는지 찾기 어렵다.

page와 database를 함께 쓰는 Notion OAuth 앱의 공유 범위를 나눈 비교표다.

이미 403 restricted_resource와 404 object_not_found 분리 글을 읽었다면, 이 표는 그 응답 차이를 권한 설계 단계에서 미리 줄이는 방향이라고 볼 수 있다.

마지막 자료는 설치 토큰을 받기 전에 점검할 질문 목록이다. page picker 안내 문구와 capability 설정을 이 표에 맞춰두면 설치 실패가 줄어든다.

Notion OAuth 설치 전에 page, database, capability 범위를 점검하는 체크리스트다.

이 체크리스트가 있으면 post 79의 404 분기나 post 58의 403 분기를 사용자 설치 직후부터 줄일 수 있다. 설계 단계에서 막을 수 있는 오류를 런타임에 진단하지 않아도 되기 때문이다.

5. 주의사항과 리스크

첫 번째 리스크는 page picker로 고른 범위가 source database까지 자동 확장된다고 보는 것이다. 두 번째 리스크는 404를 모두 잘못된 ID로만 해석해 공유 누락을 놓치는 것이다. 세 번째 리스크는 relation 대상 database를 빼고도 schema가 온전할 것처럼 기대하는 것이다.

설치 전에 최소한 '사용자가 고를 page', '원본 database 위치', 'relation 대상 database 유무', '필요 capability'를 한 표로 고정하는 편이 좋다. Notion OAuth는 이 표가 없으면 성공하는 워크스페이스와 실패하는 워크스페이스가 쉽게 갈린다.

• page picker 범위와 endpoint capability는 별개다.
• linked database는 source database 공유가 따로 필요하다.
• relation 대상 database도 설치 범위 설계에 포함한다.

6. 결론

Notion OAuth 설치 토큰으로 page와 database를 같이 쓰려면 parent page만 고르는 설계로는 부족한 경우가 많다. source database, relation 대상 database, capability를 따로 나눠 설계하면 403과 404를 설치 단계에서 훨씬 덜 만든다.

• page, source database, relation database를 따로 본다.
• 403은 capability, 404는 공유 범위를 먼저 의심한다.
• linked database는 원본 source까지 안내한다.

7. 참고 링크

1. https://developers.notion.com/guides/get-started/public-connections
2. https://developers.notion.com/guides/get-started/authorization
3. https://developers.notion.com/reference/post-database-query
4. https://developers.notion.com/reference/retrieve-a-database
5. https://developers.notion.com/guides/data-apis/working-with-databases
6. https://developers.notion.com/reference/status-codes