[업무 자동화] 노션 API 연동 2분만에 끝내기 (키 발급부터 DB 연결까지)

업무 자동화 파이프라인 구축 시 노션을 데이터베이스(DB)로 활용하는 경우가 많습니다.
외부 스크립트와의 안정적인 통신을 위해 반드시 거쳐야 하는 API 연동 및 권한 설정 프로세스를 정리합니다.

1. 프라이빗 통합(Internal Integration) 생성

노션 워크스페이스와 외부 환경(Python, Node.js 등)을 연결하기 위한 시크릿 키(Secret Key)를 생성해야 합니다.
1) Notion Developers - My Integrations 접속.
2)   [+ New integration] 클릭.
3)   Basic Information 설정:
- Name: 연동 목적에 맞는 명칭 부여 (예: Inventory_Automation_Bot)
- Workspace: 키를 적용할 워크스페이스 선택.
4) Internal Integration Secret: 생성된 secret_... 문자열을 안전한 곳에 저장합니다.
- Note: 해당 키는 외부에 노출되지 않도록 .env 또는 환경 변수로 관리하며, 유출 시 즉시 재생성(Refresh) 해야 합니다.

2. 데이터베이스(DB) 접근 권한 부여

API 키를 생성했다고 해서 모든 페이지에 접근할 수 있는 것은 아닙니다. 대상이 되는 각 데이터베이스나 페이지 단위로 해당 통합(Integration)을 명시적으로 '초대'해야 합니다.
1. 연동할 노션 데이터베이스(표) 페이지로 이동합니다.
2. 우측 상단 ... (옵션) 버튼 클릭 ➔ [연결 추가(Add connections)] 선택.
3. 앞서 생성한 통합의 이름을 검색하여 추가합니다.
4. 정상적으로 추가되면 해당 통합 봇이 페이지 내 데이터를 읽고 쓸 수 있는 권한을 얻게 됩니다.

3. 기술적 유의사항 및 권한 제어

• Response Code 403: API 호출 시 403 Forbidden 에러가 발생한다면, 대개 2단계의 연결 추가 과정이 누락된 경우입니다.
• Capabilities 설정: 통합 설정 메뉴에서 콘텐츠 읽기, 업데이트, 삽입 등 상세 권한을 목적에 맞게 제한하여 보안 수준을 유지할 수 있습니다.
• ID 확인: 데이터 적재를 위해 데이터베이스 ID가 필요할 경우, 해당 페이지 URL에서 notion.so/ 뒤부터 ?v= 앞까지의 32자리 문자열을 사용합니다.

Summary

노션 API 연동의 핵심은 정확한 시크릿 키 관리와 대상 페이지별 개별 권한 부여입니다. 데이터 적재 전, 노션의 데이터베이스 스키마(Property Types)를 명확히 정의해야 API 통신 과정에서의 타입 불일치 에러를 방지할 수 있습니다.