노션 API 연동 방법을 찾아 헤매던 중 인증 토큰 오류로 인해 작업이 멈춰버린 상황이라면 지금 바로 원인을 파악해야 합니다. 노션은 강력한 데이터베이스 기능을 제공하지만, 이를 외부 서비스나 프로그램과 연결하기 위해서는 정교한 인증 과정이 필요합니다. 이러한 오류는 대부분 데이터베이스에 대한 접근 권한이 제대로 공유되지 않았거나, 토큰 정보가 잘못 입력되었기 때문에 발생합니다. 단순히 URL만 복사한다고 해서 데이터가 읽히는 것이 아니며, 노션의 보안 정책에 따른 정확한 권한 설정이 필수적입니다. 이 글에서는 노션 공식 개발자 가이드를 참고하여 토큰 발급부터 데이터베이스 연결까지, 오류 없이 완료하는 노션 API 연동 방법을 구체적인 절차와 함께 상세히 설명합니다. 초보자도 따라 할 수 있도록 각 단계별로 발생할 수 있는 문제점과 그 해결책을 함께 다루어 안정적인 연동 환경을 구축할 수 있도록 돕겠습니다.
함께 보면 좋은 글: 시간 없는 프리랜서가 바로 쓰는 노션 템플릿 추천 10
- 노션 개발자 툴에서 내부 통합 토큰을 생성하는 절차와 보안 관리 요령
- 데이터베이스 URL에서 32자리 ID를 정확히 추출하여 연동 설정하는 방법
- curl 명령어를 통해 401 Unauthorized 오류를 해결하고 연결을 확인하는 단계
- Python 라이브러리를 활용하여 실제 데이터를 조회하는 자동화 예시 코드
- 연동 실패 시 원인을 좁혀가는 시스템적인 트러블슈팅 가이드
노션 API를 손쉽게 연동해 DB를 안전하게 연결하고, 인증 토큰 발급부터 쿼리 실행까지 4단계만으로 오류 없이 바로 적용할 수 있습니다.
통합 생성 및 내부 통합 토큰 발급: 노션 API 연동 방법의 첫 단계
API를 사용하려면 먼저 노션 시스템에서 내 애플리케이션을 식별할 수 있는 신분증과 같은 토큰을 발급받아야 합니다. 이 과정을 '내부 통합(Integration)' 생성이라고 하며, 노션은 2020년 이후부터 이 기능을 공식적으로 지원하여 외부 서비스와의 데이터 교환을 가능하게 했습니다. 내부 통합은 사용자가 소유한 워크스페이스 내에서만 작동하는 비공개 애플리케이션처럼 작동하며, 별도의 복잡한 OAuth 로그인 과정 없이 토큰 하나로 접근 권한을 관리할 수 있다는 장점이 있습니다. 토큰은 절대 타인에게 노출되면 안 되는 민감한 정보이므로 발급 즉시 안전한 곳에 보관해야 합니다.
노션 공식 개발자 문서에 따르면 모든 API 요청은 HTTPS 프로토콜을 통해 이루어져야 하며, 요청 헤더에 이 토큰을 포함해야만 인증이 완료됩니다. 토큰 없이는 단순한 조회조차 불가능하므로, 이 단계는 전체 과정 중 가장 기초적이면서도 중요한 단계입니다. 또한, 통합을 생성할 때 어떤 기능(Capabilities)을 허용할지 설정해야 하는데, 처음에는 모든 권한을 허용한 뒤 필요에 따라 제한하는 것이 편리합니다. 이제 단계별로 토큰을 발급받는 과정을 살펴보겠습니다.
내부 통합 페이지 접속
브라우저 주소창에 https://www.notion.so/my-integrations을 입력하여 접속합니다. 이 페이지는 노션에 로그인된 상태여야만 접근이 가능합니다.
새 통합 만들기
화면 우측 상단의 '+ New integration' 버튼을 클릭하여 새로운 통합 생성을 시작합니다. 만약 버튼이 보이지 않는다면 해당 워크스페이스에서 통합 생성 권한이 없는 것일 수 있으니 관리자에게 문의해야 합니다.
기본 정보 입력
이름, 로고, 연결할 워크스페이스를 선택합니다. 이름은 추후 여러 통합을 사용할 때 식별용으로 쓰이므로 직관적인 이름(예: 'My Project Automation')을 추천합니다. 로고는 선택 사항이지만 식별을 위해 채워주는 것이 좋습니다.
기능(Capabilities) 설정
'User capabilities'와 'Content capabilities' 섹션에서 이 통합이 수행할 작업을 체크합니다. 일반적인 데이터베이스 조작을 위해서는 'Read content', 'Update content', 'Insert content' 정도를 허용하면 무방합니다.
토큰 발급 및 복사
하단의 'Internal Integration Token' 섹션의 'Show' 또는 'Copy' 버튼을 눌러 secret_로 시작하는 긴 키를 확인하고 즉시 안전한 메모장이나 비밀 관리 도구에 저장합니다.
발급된 토큰은 보안상의 이유로 화면에서 벗어나면 다시 전체를 확인할 수 없습니다. 반드시 발급되자마자 복사하여 관리하세요. 또한 이 토큰은 GitHub 같은 공개 저장소에 절대 올리면 안 됩니다. 만약 실수로 노출되었다면 즉시 해당 통합을 삭제하고 새로 발급받아야 합니다.
Photo by Julio Lopez on Pexels
데이터베이스 ID 확인 및 권한 공유 설정
토큰을 발급받았다고 바로 연결되는 것은 아닙니다. 노션의 보안 정책상, 발급받은 토큰(통합)이 특정 데이터베이스에 접근하려면 해당 데이터베이스 소유자가 명시적으로 '초대'를 해야 합니다. 많은 사용자가 이 과정을 누락하여 401 Unauthorized 오류를 겪습니다. 마치 집 열쇠(토큰)를 만들었지만, 아직 방문하고자 하는 집(데이터베이스)의 출입 명단에 내 이름을 올리지 않은 것과 같습니다. 실제 사용자들은 노션 오류 내용만 보고는 이미지 URL이 잘못되었다거나, 구글 드라이브 공유 URL처럼 링크만 있으면 접근 가능할 것이라고 착각하기 쉽습니다. 이처럼 URL이나 권한 설정은 매우 세밀한 주의가 필요합니다.
데이터베이스 ID는 데이터베이스의 고유한 주소 역할을 합니다. API 요청을 보낼 때 이 ID를 통해 노션 서버가 어떤 데이터베이스를 조작해야 할지 판단합니다. 웹 브라우저의 주소창을 보면 복잡한 문자열이 보이는데, 그중 32자리 영문과 숫자 조합이 바로 우리가 찾아야 할 ID입니다. 페이지 전체의 URL과 데이터베이스 뷰의 URL은 다를 수 있으므로, 반드시 데이터베이스가 전체 화면으로 보이는 상태의 주소창을 확인해야 합니다.
데이터베이스 URL 분석
연동하려는 데이터베이스 페이지를 엽니다. 주소창의 URL 구조는 https://www.notion.so/username/[Database-ID]?v=... 형태입니다. 여기서 ? 쿼리 스트링 시작 전까지의 32자리 문자열이 ID입니다.
ID 추출
물음표(?) 앞부분과 슬래시(/) 뒷부분에 있는 32자리 문자열을 복사합니다. 예를 들어 a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6와 같은 형태입니다. 만약 URL에 하이픈(-)이 포함되어 있다면 제거하고 32자리만 남겨야 합니다.
권한 공유 메뉴 열기
데이터베이스 페이지 우측 상단의 'Share' 버튼을 클릭합니다. 여기서 사람을 초대하는 것이 아니라, 방금 만든 '통합'을 초대해야 합니다.
통합 연결(Add connections)
공유 팝업 하단에 보면 'Connections' 혹은 'Connect to'라는 항목이 있습니다. 이곳을 클릭하고 방금 생성한 통합 이름(예: 'My Project Automation')을 검색하여 선택합니다.
연결 확인
리스트에 통합 이름이 뜨고 체크 표시가 활성화되었다면 권한 공유가 완료된 것입니다. 이제 API 요청이 수락될 준비가 되었습니다.
데이터베이스가 다른 페이지 안에 포함된 '인라인 데이터베이스'인 경우, 해당 데이터베이스를 클릭하여 전체 화면으로 펼친 뒤(Full page) 우측 상단의 '...' 메뉴에서 'Turn into'를 통해 별도 페이지로 분리하면 ID를 찾기가 훨씬 수월합니다.
API 연동 테스트 및 curl 명령어 검증
동영상으로 보는 노션 API 연동 방법
글로 충분하지 않다면 관련 영상을 함께 보세요. 클릭하면 YouTube에서 검색 결과로 이동합니다.
토큰 발급과 데이터베이스 권한 공유까지 마쳤다면, 실제로 API가 정상 작동하는지 확인해야 합니다. 복잡한 코드를 작성하기 전에, 터미널이나 명령 프롬프트에서 사용할 수 있는 curl 명령어를 통해 간단하게 테스트할 수 있습니다. 이 과정은 앞서 설정한 값들이 정확한지, 그리고 노션 서버가 우리의 요청을 승인하는지를 검증하는 가장 빠른 방법입니다. 요청을 보낼 때는 반드시 헤더(Header)에 인증 정보와 버전 정보를 포함해야 하며, 잘못된 헤더는 400 Bad Request 오류를 유발할 수 있습니다.
기본적인 조회 요청은 HTTP GET 메서드를 사용합니다. 성공적으로 연결되었다면, 노션은 JSON 형식으로 데이터베이스의 스키마 정보와 초기 데이터 목록을 반환해 줍니다. 만약 이 단계에서 오류가 발생한다면 토큰이나 ID 값의 오타, 혹은 권한 공유 누락을 의심해야 합니다. 아래 명령어를 복사하여 본인의 정보로 수정 후 실행해 보세요.
curl -X GET 'https://api.notion.com/v1/databases/[Database-ID]' \
-H 'Authorization: Bearer [Internal-Integration-Token]' \
-H 'Notion-Version: 2022-06-28'
위 명령어에서 [Database-ID]와 [Internal-Integration-Token] 부분만 실제 값으로 변경하면 됩니다. Notion-Version 헤더는 노션 API의 업데이트에 따라 호환성을 유지하기 위해 필수적입니다. 명령어 실행 결과로 긴 JSON 텍스트가 출력되고 그 안에 데이터베이스의 이름과 속성(Properties) 정보가 보인다면 연동이 100% 성공한 것입니다.
자주 발생하는 401 Unauthorized 오류 해결
노션 API 연동 체크리스트
- Notion에서 Integration 생성 →
Settings → Integrations → Develop your own integrations - API 토큰 복사 →
secret_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX를 .env 파일에NOTION_API_KEY로 저장 - 연동할 데이터베이스 페이지 열고 URL에서 Database ID 추출 (예:
https://www.notion.so/…/1234567890abcdef1234567890abcdef) - Integration에 데이터베이스 권한 부여 → 페이지 상단
Share → Invite → 검색창에 Integration 이름 입력 → 권한 ‘Can edit’ 선택 - 환경 변수 로드 후 테스트 요청 실행
curl -X GET "https://api.notion.com/v1/databases/1234567890abcdef1234567890abcdef"\n -H "Authorization: Bearer $NOTION_API_KEY"\n -H "Notion-Version: 2022-06-28" - 응답에
"object":"database"가 보이면 연동API 연동 과정에서 가장 많이 마주치는 악몽은 바로 '401 Unauthorized' 오류입니다. 이 오류는 "당신이 누구인지 모르겠거나, 여기에 들어올 자격이 없다"는 의미입니다. 원인은 단순하지만 찾아내기 까다로운 경우가 많습니다. 첫 번째 원인은 토큰 값의 불일치입니다. 토큰을 복사할 때 앞뒤 공백이 포함되었거나, 일부가 잘려서 복사되었는지 다시 한번 확인해야 합니다. 두 번째
관련 외부 자료 (자동 추천)자주 묻는 질문
Q. 노션 API 키를 어디서 발급받나요?
A. 노션 홈페이지 오른쪽 상단 프로필 → Settings & Members → Integrations → Develop your own integrations에서 새 통합을 만들면 API 키가 발급됩니다. 발급된 비밀키는 절대로 외부에 노출하지 말고 안전하게 보관하세요.
Q. 내 데이터베이스 ID를 찾는 방법이 궁금합니다.
A. 노션에서 원하는 데이터베이스 페이지를 열고 URL에서 마지막 슬래시 뒤에 있는 32자리 문자열이 데이터베이스 ID입니다. 혹은 데이터베이스를 열고 오른쪽 상단 ‘⋮⋮’ → ‘Copy link’를 클릭해도 같은 ID를 얻을 수 있습니다.
Q. 읽기 전용 권한만 부여하고 싶어요. 어떻게 설정하나요?
A. 통합을 생성할 때 권한을 ‘Read only’로 지정하거나, 기존 통합의 권한 페이지에서 해당 데이터베이스에 ‘Read’ 권한만 부여하면 됩니다. 이 경우 API는 데이터를 조회만 할 수 있고 수정은 불가능합니다.
Q. API 호출 시 오류가 계속 발생하는데 원인은 무엇인가요?
A. 주요 원인은 잘못된 헤더(Authorization에 ‘Bearer ’를 붙이지 않음), 데이터베이스 ID 오류, 혹은 API 버전 미일치입니다. 오류 메시지를 확인하고 위 세 가지 항목을 점검하면 대부분 해결됩니다.
함께 읽으면 좋은 글
MMebys Blog맥OS · 크롬 · 자동화 · AI 도구 가이드