노션 API 키 발급, 연결부터 첫 요청까지
노션 API 키 발급 후에도 페이지가 보이지 않는 이유는 무엇일까요? 내부 연결 생성과 토큰 보관, 페이지 접근 권한, 데이터베이스에 행을 추가하는 요청과 사용 제한까지 정리했습니다.
안녕하세요. 사랑받는 IT 프로덕트의 첫걸음, 똑똑한개발자입니다.
오늘의 인사이트 요약
노션 API 키 발급은 통합(지금 이름은 연결)을 만들고 API 토큰을 복사하면 끝납니다.
토큰만으로는 페이지가 열리지 않아 페이지마다 통합을 연결합니다.
이 글의 요청 예시에 사용하는 Notion-Version은 2026-03-11이고, 행 추가에는 data_source_id를 씁니다.
노션 API 키는 외부 프로그램이 노션에 요청을 보낼 때 사용하는 인증 토큰입니다. 팀 내부 자동화라면 내부 연결을 만들고, 읽거나 수정할 페이지의 접근 권한을 따로 연결합니다. 오늘은 노션 API 키 발급과 페이지 연결, 데이터베이스에 행을 추가하는 첫 요청까지 알아보겠습니다.
노션 API 통합이란 무엇이고, 어떤 방식으로 발급할까요
노션 API 통합은 워크스페이스에 들어오는 봇 계정입니다.
현재 문서에서는 통합(Integration)을 연결(Connection)이라고 부릅니다.
우리 팀 자동화라면 내부 연결을 고릅니다.
노션 문서의 발급 방식은 세 가지이고, 이 글은 내부 연결 기준입니다.
방식 | 언제 쓰나 | 토큰 | 페이지 권한 |
|---|---|---|---|
내부 연결 | 한 워크스페이스 안의 팀 자동화 | 고정 API 토큰 | 페이지마다 연결 |
공개 연결 | 다른 노션 사용자가 설치하는 앱 | OAuth 액세스 토큰 | 사용자가 설치 때 선택 |
개인 액세스 토큰 | 내 계정으로 도는 스크립트 | ntn_으로 시작하는 토큰 | 만든 사람 권한 그대로 |
노션 API 토큰 발급, 통합 생성부터 3단계로 끝납니다
첫째, 개발자 포털에서 내부 연결을 만듭니다.
app.notion.com/developers/connections에서 Internal connections를 골라 새 연결을 만듭니다(워크스페이스 소유자만 가능).
둘째, Configuration 탭에서 기능을 좁혀 둡니다.
콘텐츠 읽기·수정·삽입 기능을 켜고 끄는 곳입니다. 행만 추가한다면 읽기와 삽입만 남깁니다.
셋째, 같은 탭에서 API 토큰을 복사합니다.
토큰은 코드 대신 NOTION_API_KEY 같은 환경 변수에 둡니다.
노션 API 연동, 페이지에 권한을 줘야 열립니다
노션 API 키 발급만 하면 아무 페이지도 보이지 않습니다.
갓 만든 통합은 어느 페이지에도 접근하지 못해 오류가 납니다. 페이지 연결이 빠졌는지 먼저 확인해 보세요.
권한은 노션 페이지나 개발자 포털에서 줍니다.
노션에서는 페이지 오른쪽 위 ••• 메뉴의 연결 항목에서 연결 추가를 눌러 통합을 검색합니다. 포털에서는 Content access 탭의 Edit access로 한 번에 고릅니다. 상위 페이지에 연결하면 하위 페이지까지 열리니 범위부터 정합니다.
노션 API 사용법, 데이터베이스에 행 하나 추가하기
2025-09-03 버전부터는 data_source_id를 먼저 찾습니다.
데이터베이스 하나에 데이터 소스를 여럿 두게 바뀌어서, id는 GET /v1/databases/{database_id} 응답의 data_sources 목록에서 찾습니다.
행 추가는 POST /v1/pages 한 번이면 됩니다.
ID는 가상 값이고 Name은 제목 속성 이름에 맞춥니다.
curl -X POST 'https://api.notion.com/v1/pages' \
-H "Authorization: Bearer $NOTION_API_KEY" \
-H 'Notion-Version: 2026-03-11' \
-H 'Content-Type: application/json' \
--data '{"parent":{"type":"data_source_id","data_source_id":"YOUR_DATA_SOURCE_ID"},
"properties":{"Name":{"title":[{"text":{"content":"신규 문의"}}]}}}'
노션 API 사용법에서 놓치기 쉬운 요청 제한
요청 제한은 요금제와 API 종류에 따라 다릅니다.
연결별 요청 한도는 비즈니스·엔터프라이즈 요금제에서 분당 600회, 그 외 요금제에서 분당 180회입니다. 데이터 소스 조회에는 연결별 초당 약 3회의 별도 제한이 있고, 워크스페이스의 공유 한도도 적용됩니다. 429 응답을 받으면 Retry-After에 표시된 시간만큼 기다린 뒤 재시도합니다.
한 번에 보내는 양에도 상한이 있습니다.
rich text의 text.content는 2,000자, 블록 배열은 100개가 상한입니다. 요청 전체의 크기 제한도 있으므로 긴 콘텐츠를 전송할 때는 항목별 한도를 함께 확인합니다.
노션 API 키 발급은 금방이어도 정할 것이 남습니다. 이 노션 데이터베이스를 언제까지 서비스의 저장소로 쓸 건가요? 주문·회원 정보까지 올라가면 요청 제한과 권한 관리가 발목을 잡습니다.
구체적인 설정과 사용 조건은 노션 연결·페이지 권한 안내 · 노션 API 요청 제한에서 더 자세히 보실 수 있습니다.
노션의 데이터를 실제 업무와 연결하려면
똑똑한개발자는 웹·앱과 관리자 시스템을 만들고, 기존 시스템의 API를 연결하는 개발을 함께합니다. 자체 B2B 운영 관리 SaaS인 플러그(pluuug)를 출시하고 고도화한 경험도 갖고 있는데요. 문의나 계약 데이터를 다룰 때는 화면에서 보이는 정보뿐 아니라 누가 입력하고 수정하는지도 함께 살펴볼 수 있습니다.
노션에 쌓인 데이터를 다른 서비스와 연결하고 싶으신가요? 아래 똑똑한개발자 링크로 문의해 주시면 연동할 데이터와 접근 권한, 필요한 관리 화면을 함께 검토하겠습니다.
감사합니다. :)
노션 API 토큰 발급과 페이지 권한 연결을 정리합니다.
https://www.toktokhan.dev/contact?utm_source=landing&utm_campaign=notion-api-key&utm_medium=notion-api-key&utm_term=%EB%85%B8%EC%85%98-api-%ED%82%A4-%EB%B0%9C%EA%B8%89