[Notion API][통합] internal connection과 public OAuth를 언제 나눠야 하나

IT 리서치 노트

[Notion API][통합] internal connection과 public OAuth를 언제 나눠야 하나

Notion API를 처음 붙일 때 가장 먼저 정해야 하는 것은 endpoint가 아니라 연결 방식이다. internal connection은 한 workspace 안에서 빠르게 시작하기 좋고, public OAuth는 여러 workspace에 배포할 때 필요하다. 문제는 많은 팀이 internal connection으로 출발한 뒤 나중에 외부 설치형 제품으로 확장하면서 권한과 토큰 구조를 다시 뜯어고친다는 점이다. 이 글은 지금 어떤 연결을 고르면 나중에 덜 고생하는지 기준을 정리한다.

목차

1. 개요
2. 어디서 막히는가
3. 실제로 해결하는 순서
4. 화면과 출력으로 확인하기
5. 주의할 점
6. 결론
7. 참고 링크

1. 개요

Notion API를 처음 붙일 때 가장 먼저 정해야 하는 것은 endpoint가 아니라 연결 방식이다. internal connection은 한 workspace 안에서 빠르게 시작하기 좋고, public OAuth는 여러 workspace에 배포할 때 필요하다.

문제는 많은 팀이 internal connection으로 출발한 뒤 나중에 외부 설치형 제품으로 확장하면서 권한과 토큰 구조를 다시 뜯어고친다는 점이다. 이 글은 지금 어떤 연결을 고르면 나중에 덜 고생하는지 기준을 정리한다.

연결 방식을 이미 골랐다면 다음 단계는 callback 실패와 capability 누락을 분리해서 보는 것이다. 그 흐름은 [Notion API][OAuth] redirect URI와 capabilities가 맞지 않을 때 먼저 볼 화면에서 이어서 정리했다.

• 이 글은 현재 공식 문서와 공개 도움말을 다시 확인한 뒤 정리했다.
• 설정 경로, 실패 지점, 검증 결과를 분리해서 읽으면 바로 실행에 옮기기 쉽다.
• 실제 운영에서는 권한, 비용, 배포 로그를 함께 봐야 같은 실수를 반복하지 않는다.

2. 어디서 막히는가

문제가 길게 보이더라도 실제 막힘은 몇 가지 패턴으로 모인다. 아래 증상 중 하나라도 보이면 설정값, 요청값, 실행 결과를 분리해서 기록하는 쪽이 빠르다.

• 사내 자동화인데도 public OAuth를 먼저 붙여 구현과 검토 범위가 커진다.
• 여러 고객 workspace 설치가 필요한데 internal token 방식으로 시작해 나중에 구조를 바꾼다.
• workspace 권한과 사용자별 설치 흐름을 혼동해 접근 오류가 반복된다.
• 토큰 발급과 저장 위치를 분리하지 않아 운영 중 회전과 해지가 어렵다.

여기서 가장 흔한 실수는 증상만 보고 권한을 넓히거나 비용 플랜을 올리거나, 별도 로그 없이 다시 시도하는 것이다. 그러면 당장은 지나가도 다음 배포나 다음 운영 시간대에 같은 문제가 다시 나온다.

따라서 먼저 실제 값과 공식 기준이 어떻게 다른지 좁히고, 그 다음에 클릭, 입력, 실행, 저장 순서를 하나씩 재현해야 한다. 이 순서가 있어야 팀원끼리 같은 결과를 볼 수 있다.

문제정의 단계에서는 오류 문구 한 줄만 보는 대신, 어떤 메뉴에서 확인했고 어떤 필드가 비어 있었는지, 어떤 응답 상태가 먼저 나타났는지까지 적어두는 편이 좋다. 그래야 해결 단계에서 값을 바꾼 뒤에도 같은 기준으로 성공과 실패를 다시 비교할 수 있다.

특히 비용 문제나 권한 문제는 겉으로는 비슷하게 보여도 원인이 다르다. 청구 화면, 콘솔 설정, 배포 로그, 브라우저 요청, CLI 출력 가운데 무엇이 기준 화면인지 먼저 정하고 그 화면을 중심으로 확인해야 엉뚱한 메뉴를 오래 헤매지 않는다.

3. 실제로 해결하는 순서

아래 순서는 메뉴를 열고 값을 확인하고 결과를 다시 보는 실무용 순서다. 한 번에 모두 바꾸지 말고 한 단계씩 적용한 뒤 출력과 화면을 확인하는 편이 안전하다.

1. 먼저 연결 대상이 한 workspace인지 여러 workspace인지 결정한다.
2. 사내 도구라면 internal connection으로 빠르게 시작하고 공유 대상 페이지 권한을 확인한다.
3. 외부 고객 설치형이면 public OAuth와 token exchange 저장 구조를 먼저 설계한다.
4. 나중에 public으로 갈 가능성이 크면 연결 추상화 계층을 초기에 나눠 둔다.

안전한 예제 코드

type NotionAuthMode = "internal" | "oauth";

function resolveNotionClient(mode: NotionAuthMode) {
  if (mode === "internal") {
    return { token: process.env.NOTION_INTERNAL_TOKEN || "YOUR_INTERNAL_TOKEN" };
  }
  return { token: "exchange authorization code on server" };
}

핵심은 코드에서 인증 모드를 분리하는 것이다. 실제 토큰과 client secret은 서버 환경변수로만 관리한다.

예제 코드는 흐름만 남겼다. 실제 토큰, 계정, 내부 서버 주소, 비공개 저장소 이름은 placeholder로 바꾸고 서버 환경변수나 보안 저장소로 분리한다.

중요한 점은 설정 변경 직후 바로 다음 단계로 넘어가지 않는 것이다. 각 단계마다 어떤 메뉴를 클릭했고, 어떤 값을 입력했고, 어떤 출력이 돌아왔는지 짧게라도 기록해야 한다. 그래야 실패했을 때 마지막으로 바뀐 값이 무엇인지 빠르게 되짚을 수 있다.

또한 해결 절차는 한 번 성공했다고 끝나지 않는다. 같은 절차를 다른 환경이나 다른 브랜치, 다른 계정에서도 다시 실행해 보고 결과가 같은지 확인해야 한다. 운영 환경과 로컬 환경의 URL, 권한, 캐시, 플랜, 리전 차이가 숨어 있으면 여기서 드러나는 경우가 많다.

4. Notion 인증 문서에서 나눠 볼 부분

Notion 통합은 internal connection과 public OAuth를 같은 인증 문제로 묶으면 적용 범위를 잘못 잡기 쉽다. 아래 화면에서는 권한 부여, 내부 연결, 공개 OAuth의 차이를 순서대로 확인한다.

먼저 Authorization 문서에서 Notion API가 어떤 방식으로 접근 권한을 받는지 확인한다. integration token과 OAuth 흐름을 같은 것으로 보면 안 된다.

Authorization 문서에서는 Notion API 접근 권한을 얻는 기본 방식을 확인한다.

내부 연결 흐름은 팀 안에서 쓰는 자동화에 맞다. 사용자가 직접 설치하고 동의해야 하는 공개 앱과는 설정 위치부터 다르다.

Internal connection auth flow 화면에서는 내부 자동화용 token 설정 흐름을 확인한다.

Internal connections 문서에서는 권한 범위와 페이지 공유 조건을 확인한다. token이 있어도 연결된 페이지가 아니면 접근할 수 없다는 점이 중요하다.

Internal connections 화면에서는 내부 통합이 workspace와 페이지 권한에 어떻게 묶이는지 확인한다.

권한 동작 설명은 장애 대응에 필요하다. API가 403을 반환할 때 token 문제인지, 페이지 공유 문제인지 여기서 갈린다.

How permissions work 화면에서는 페이지 공유와 integration 권한이 함께 필요하다는 기준을 확인한다.

Public connections 문서는 외부 사용자에게 설치시키는 앱인지 판단할 때 본다. 배포 대상이 workspace 내부인지 외부 고객인지에 따라 인증 설계가 달라진다.

Public connections 비교 화면에서는 내부 연결과 공개 OAuth 앱의 적용 대상을 나눠 확인한다.

이 순서로 확인하면 문서의 기능 설명, 설정 범위, 제한 조건, 실제 운영 판단 기준을 한 번에 대조할 수 있다. 화면에서 먼저 볼 항목을 정한 뒤 코드나 콘솔 설정을 수정해야 같은 문제가 반복되지 않는다.

5. 주의할 점

설정을 맞췄더라도 운영에서는 다시 틀어지는 지점이 있다. 아래 항목은 배포 직전과 배포 직후에 꼭 다시 점검할 부분이다.

• public OAuth를 과하게 빨리 도입하면 구현과 심사 부담이 늘어난다.
• internal token을 여러 고객 환경에 복사해 쓰면 보안과 운영이 모두 꼬인다.
• 페이지 공유 권한을 빼먹으면 연결은 성공했는데 데이터가 비어 보일 수 있다.

특히 권한, 비용, 캐시, 재시도 정책은 한 번 맞춘 뒤에도 환경이 바뀌면 다시 확인해야 한다. 문서가 바뀌었는지, 콘솔 기본값이 달라졌는지, 팀의 배포 방식이 바뀌었는지도 같이 본다.

6. 결론

사내 문서 자동화면 internal connection이 기본값이다.

• 사내 문서 자동화면 internal connection이 기본값이다.
• 외부 고객이 자기 workspace에 설치해야 하면 public OAuth를 택한다.
• 두 경우를 모두 대비해야 하면 토큰 저장과 client 생성 코드를 초기에 분리한다.

핵심은 추상적인 '좋은 설정'을 찾는 것이 아니라, 지금 내 서비스에서 어떤 값과 어떤 출력이 정답인지 빠르게 확인하는 것이다. 이 글의 순서대로 문서, 설정, 실행 결과를 묶어 보면 같은 문제를 다시 만났을 때 훨씬 빨리 끝낼 수 있다.

실제 장애 대응 단계까지 바로 이어 보려면 redirect URI와 capabilities 확인 순서를 함께 보면 internal connection과 public OAuth를 고른 뒤 무엇을 먼저 점검해야 하는지 끊김 없이 이어진다.

7. 참고 링크

1. https://developers.notion.com/guides/get-started/authorization
2. https://developers.notion.com/guides/get-started/internal-connections
3. https://developers.notion.com/guides/get-started/public-connections