Skip to content

Notion API 인증

개요

Notion에 접근하려면 "누가, 어느 워크스페이스의 무엇을 읽는지"를 증명해야 해요. Notion API는 이 인증을 몇 가지 길로 나눠 제공해요. 크게 내부 연결(Internal integration, 정적 토큰), 개인 액세스 토큰(PAT), 그리고 외부 사용자용 OAuth 2.0이에요. 어느 것을 쓰느냐는 "누구의 콘텐츠에 접근하는가"가 기준이 돼요. 이 페이지는 공식 문서 기준으로 각 인증 흐름과 토큰을 안전하게 다루는 법을 풀어요.

핵심 개념

세 가지 인증 방식

Notion 공식 문서는 인증을 세 갈래로 나눠요.

  • 내부 연결(Internal connection) — 내가 제어하는 워크스페이스에만 접근할 때 쓰는 정적 API 토큰이에요. Developer 포털에서 연결(connection)을 만들면 설치 액세스 토큰(installation access token) 을 받아요. 연결은 만든 워크스페이스와 묶이고, 워크스페이스 오너여야 만들어요.
  • 개인 액세스 토큰(PAT) — 사용자 범위의 정적 API 토큰이에요. 특정 사용자를 대신해 접근할 때 써요.
  • 공개 연결(Public connection, OAuth 2.0) — 내가 제어하지 않는 다른 사용자의 콘텐츠에 접근할 때 쓰는 표준 OAuth 2.0 흐름이에요. 사용자가 "이 앱에 Notion 접근을 허용"하면 액세스 토큰을 받아 대신 요청해요.

내부 연결로 API 요청하기

모든 REST 요청에 인증 토큰을 Authorization 헤더로 보내요. SDK를 쓰면 클라이언트 초기화 때 토큰을 한 번만 설정하면 됐어요.

GET /v1/pages/b55c9c91-384d-452b-81db-d1ef79372b75 HTTP/1.1
Authorization: Bearer {INTEGRATION_TOKEN}

const { Client } = require("@notionhq/client")
const notion = new Client({ auth: process.env.NOTION_TOKEN })

SDK를 안 쓰고 직접 REST를 호출한다면 Notion-Version과 Content-type 헤더까지 따로 설정해야 해요. Notion 버전은 날짜 형식(예: 2026-...)으로 지정해요.

페이지를 연결과 공유하기

내부 연결은 만들었다고 바로 모든 페이지에 접근할 수 있는 게 아니에요. 페이지를 연결(connection)과 공유해야 해요. Notion 페이지 우상단 메뉴에서 Add connections로 연결을 추가하면, 그 연결은 해당 페이지에 API 요청을 할 수 있어요. 공유되지 않은 페이지에 요청하면 오류가 나요.

토큰 보안

설치 액세스 토큰은 비밀이에요. 공식 문서는 토큰을 소스 코드나 버전 관리 시스템에 커밋하지 말고, 환경 변수나 시크릿 매니저로 관리하라고 강조해요. 토큰이 유출되면 그 연결이 접근 가능한 워크스페이스 데이터가 노출될 수 있으니 취급을 조심해야 해요.

실제 적용 (데이터스케쳐스)

웹빌더에서 Notion 콘텐츠를 가져오는 경로는 "누구의 워크스페이스를 읽는가" 에 따라 인증 방법이 갈라져요. 우리 시스템이 직접 제어하는 콘텐츠 하나를 읽는 거라면 내부 연결 토큰으로도 충분하고, 고객마다 자기 워크스페이스를 연동해주는 기능이라면 OAuth로 사용자 동의를 받아야 해요.

운영할 때 가장 신경 쓸 부분은 토큰의 수명과 유출이에요. OAuth 토큰은 상황에 따라 만료될 수 있고, 토큰이 환경 변수에 안전하게 보관되어야 해요. 또 토큰이 어느 페이지에 접근 가능한지를 공유 설정으로 통제해야, 의도치 않은 콘텐츠 노출을 막아요. 인증 후 페이지·DB를 읽는 방법은 데이터베이스 질의, 변경을 실시간으로 받는 방법은 웹훅에서 이어져요.

더 알아보기