Notion API 키를 발급받고 요청에 필요한 ID를 찾는 방법

Notion API 키는 코드가 Notion API에 요청을 보낼 때마다 함께 전송하는 토큰이에요. 2026년 기준으로 세 가지가 있어요. 나를 대신해 작업하는 개인 액세스 토큰, 팀 자동화를 위한 내부 연결 토큰, 그리고 다른 사람들이 설치하는 앱을 위한 OAuth예요. 아래에서는 각각을 만드는 방법, 각각에 내 페이지 접근 권한을 부여하는 방법, 요청에 필요한 페이지·데이터베이스·데이터 소스 ID를 찾는 방법, 그리고 거의 모든 사람이 처음 시도할 때 겪는 오류를 해결하는 방법을 알아볼게요.

어떤 Notion API 키가 필요한가요?

노션 개발자 문서에는 세 가지 인증 방식이 나와 있어요. 각 방식은 토큰에 누구의 권한이 부여되는지, 토큰으로 무엇을 볼 수 있는지, 누가 토큰을 생성할 수 있는지가 달라요.

빠르게 선택하는 방법:

• 혼자 쓰는 스크립트, 노트북 또는 도구: 개인 액세스 토큰을 사용하세요. 공유할 필요 없이 2분이면 바로 쓸 수 있어요.
• 팀이 의존하는 자동화: 내부 연결을 사용하세요. 설정한 사람이 떠나도 계속 작동하며, 해당 연결에 공유한 페이지만 볼 수 있어요.
• 다른 사람들이 설치하는 앱: OAuth를 사용하는 공개 연결을 선택하세요. 사용자에게 토큰을 붙여넣으라고 절대 요청하지 마세요.
• Claude, ChatGPT, Cursor 또는 다른 AI 앱: 대개 키가 전혀 필요 없어요. 노션에서 호스팅하는 MCP 서버를 이용하면 OAuth로 로그인할 수 있어요. 설정 방법은 Notion MCP 가이드에서 확인하세요.

옵션 1: 개인 액세스 토큰 만들기

개인용 액세스 토큰(PAT)은 내 워크스페이스 멤버십과 페이지 권한으로 나를 대신해 작동해요. 노션의 공식 API 빠른 시작 가이드도 이 토큰으로 시작해요. 토큰 외에는 따로 설정할 것이 없기 때문이에요.

1. 개발자 모드를 켜세요. 노션에서 설정을 열고 개발자 모드를 검색해 켜세요. 로컬 설정이라 브라우저와 데스크톱 앱에서 각각 켜야 하며, 모바일에서는 사용할 수 없어요.
2. 토큰 목록을 여세요. 사이드바에 개발자 섹션이 나타나요. 개인 액세스 토큰을 열고 새 토큰을 클릭하세요. 직접 링크는 notion.so/developers/tokens예요.
3. 이름을 지정하고 범위를 설정하세요. Notion API 기능을 선택하고(노션 Workers를 배포하는 경우에만 Workers도 추가하세요), 만료 기간을 7일, 30일, 90일, 180일 또는 기본값인 1년 중에서 선택하세요. 워크스페이스 선택 화면이 나타나면 워크스페이스를 선택하세요. 토큰은 하나의 워크스페이스에 속해요.
4. 토큰 만들기를 클릭하고 값을 바로 복사하세요. 노션은 토큰 값을 한 번만 보여주며, 이후에는 관리자에게도 다시 보여주지 않아요. 비밀번호 관리 도구나 프로젝트의 시크릿 저장소에 보관하세요.

새 토큰은 ntn_로 시작해요. 노션은 2024년 9월 25일에 토큰 접두사를 secret_에서 변경했으며, 이전 토큰도 계속 사용할 수 있어요. 다만 코드에서 접두사를 검사하지는 마세요. 노션은 토큰 형식이 바뀔 수 있다고 안내하며, 개발자에게 토큰의 내부 구조를 해석하지 말고 문자열 그대로 취급해 달라고 요청하고 있어요.

토큰을 만들 수 없나요?

게스트와 제한된 멤버는 PAT를 아예 생성할 수 없어요. 그 외 멤버 중 누가 Notion API에 접근할 수 있는 PAT를 생성할 수 있는지는 요금제에 따라 달라져요.

Business 및 Enterprise에서는 워크스페이스 소유자에게 설정 → 연결에서 허용해 달라고 요청하세요. 이후 관리자가 정책의 허용 범위를 좁히면 기존 토큰이 더 이상 작동하지 않고 unauthorized를 반환해요.

PAT로 접근할 수 있는 범위

해당 워크스페이스에서 사용자가 열 수 있는 모든 항목에 접근할 수 있어요. 페이지, 데이터베이스, 댓글, 파일까지 모두 포함돼요. 페이지를 PAT에 따로 공유할 필요도 없어요. 그래서 PAT를 빠르게 사용할 수 있지만, PAT가 유출되면 피해도 커져요. 노션 문서에는 읽기 전용 PAT가 설명되어 있지 않아요. Notion API 권한으로 읽기, 생성, 업데이트가 가능해요. 몇 개의 페이지를 읽기만 하면 되는 작업이라면 콘텐츠 읽기 권한만 부여한 내부 연결이 더 안전한 키예요. 사용자가 페이지 접근 권한을 잃거나 워크스페이스를 나가면 토큰도 해당 접근 권한을 잃어요.

옵션 2: 내부 연결 토큰 만들기

내부 연결은 하나의 워크스페이스에 속한 봇 사용자예요. 팀이 의존하는 자동화나 사용자가 열 수 있는 모든 페이지가 아닌 일부 페이지에만 접근해야 하는 도구에 사용하세요. 예전 가이드에서는 이를 “내부 통합”이라고 부르고, 해당 토큰은 “내부 통합 시크릿” 또는 “통합 토큰”이라고 불러요.

1. 워크스페이스 소유자인지 확인하세요. 소유자만 연결을 만들 수 있어요. 소유자가 아니라면 소유자에게 요청하거나, 노션 FAQ의 안내처럼 무료 개인 워크스페이스를 만들어 테스트해 보세요.
2. 연결을 만드세요. 사이드바의 개발자 섹션이나 notion.so/developers에서 내부 연결을 열고 새 연결 만들기를 클릭한 다음, 이름을 입력하고 워크스페이스를 선택하세요. 연결은 나중에 다른 워크스페이스로 옮길 수 없어요. 다른 워크스페이스에서 사용하려면 그곳에 새 연결을 만들어야 해요.
3. API 토큰을 복사하세요. 연결의 구성 탭을 열고 API 토큰을 복사하세요. 소유자는 설정 → 연결에서도 토큰을 확인할 수 있어요. 연결 옆의 ••• 메뉴에 토큰을 가져오는 옵션이 있어요.
4. 같은 탭에서 기능을 설정하세요(목록은 아래에 있어요).
5. 페이지 접근 권한을 부여하세요. 새 연결은 아무 콘텐츠에도 접근할 수 없으며, 콘텐츠를 공유하기 전까지는 모든 요청이 실패해요. 콘텐츠 접근 탭에서 접근 권한 편집을 클릭하고 페이지와 데이터베이스를 선택하세요. 또는 노션에서 페이지를 열고 오른쪽 상단의 •••를 클릭한 다음, 연결을 찾아 연결 추가를 선택하고 만든 연결을 검색하세요. 페이지를 공유하면 하위 페이지도 함께 공유돼요.

토큰이 볼 수 있는 페이지에서도 수행할 수 있는 작업은 권한에 따라 제한돼요. 노션 문서에서는 필요한 최소한의 권한만 요청하도록 권장해요:

• 콘텐츠 읽기, 콘텐츠 업데이트, 콘텐츠 삽입 권한을 원하는 대로 조합할 수 있어요. 내보내기에는 콘텐츠 읽기 권한만 필요해요. 행을 추가하는 양식에는 콘텐츠 삽입 권한만 필요해요. 상태를 설정하는 스크립트에는 콘텐츠 업데이트 권한만 필요해요.
• 댓글 읽기, 댓글 삽입.
• 사용자 정보: 없음, 이메일 주소 제외, 이메일 주소 포함 중에서 선택할 수 있어요.

연결은 독립적인 사용자이므로 액세스 권한이 특정 사람에게 종속되지 않아요. 페이지를 공유한 팀원이 워크스페이스를 떠나도 연결은 해당 페이지에 계속 액세스할 수 있어요. 모든 워크스페이스 소유자는 다른 사람이 만든 연결을 포함해 모든 내부 연결을 볼 수 있어요.

옵션 3: 다른 사람이 사용하는 앱을 위한 OAuth

제품을 개발하고 있다면 사용자에게 토큰을 붙여 넣으라고 요청하지 마세요. 대신 공개 연결을 만드세요. 각 사용자가 노션의 OAuth 창에서 로그인하고 앱이 볼 수 있는 페이지를 선택하는 방식이에요. 직접 관리하는 서버에서 OAuth 코드를 토큰으로 교환하세요. 클라이언트 시크릿은 절대로 브라우저에 전달되어서는 안 되며, 노션의 OAuth 토큰 엔드포인트는 의도적으로 브라우저 코드에서 접근할 수 없도록 차단되어 있어요. IVGraph도 이 방식으로 연결해요. 노션 창에서 페이지를 선택하기만 하면 되고, 키를 직접 다룰 일은 없어요.

요청 한 번으로 키를 테스트해 보세요

토큰은 코드에 넣지 말고 환경 변수에 저장하세요. macOS 또는 Linux에서는 다음과 같이 설정하세요:

export NOTION_API_KEY="ntn_…"

Windows PowerShell에서는 $env:NOTION_API_KEY = "ntn_…"를 사용해요. 그런 다음 노션에 토큰 소유자가 누구인지 물어보세요:

curl https://api.notion.com/v1/users/me \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2026-03-11"

정상적으로 작동하는 키는 bot 유형의 사용자를 반환해요. 개인 액세스 토큰이라면 소유자는 본인이에요. 다음으로 키로 어디까지 접근할 수 있는지 확인해 보세요. 검색어 없이 검색하면 토큰으로 접근할 수 있는 모든 페이지와 데이터 소스가 반환돼요. 이 필터는 본인의 데이터베이스에 속한 데이터 소스만 남기며, 각 데이터 소스에는 자체 ID와 상위 데이터베이스의 ID가 포함돼요.

curl -X POST https://api.notion.com/v1/search \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{"filter": {"property": "object", "value": "data_source"}}'

모든 요청에는 Notion-Version 헤더가 필요해요. 최신 버전은 2026-03-11이에요. JavaScript용 공식 SDK는 토큰을 한 번만 전달하면 되고, 요청 속도 제한에 걸린 요청은 자동으로 재시도해요. 현재 릴리스는 기본적으로 2025-09-03을 전송하므로 버전을 명시적으로 설정해 주세요:

import { Client } from "@notionhq/client";

const notion = new Client({
  auth: process.env.NOTION_API_KEY,
  notionVersion: "2026-03-11",
});

const me = await notion.users.me({});
console.log(me.type, me.name);

페이지, 데이터베이스 또는 블록 ID는 어디에서 찾을 수 있나요?

노션의 모든 페이지, 데이터베이스, 블록에는 32개의 16진수 문자로 이루어진 UUID가 ID로 부여돼요. 링크에는 대시 없이 표시되며, API에서는 대시 유무에 관계없이 사용할 수 있어요. 대시를 넣으면 8-4-4-4-12 단위로 나뉘므로, 1429989fe8ac4effbc8f57f56486db54는 1429989f-e8ac-4eff-bc8f-57f56486db54가 돼요.

가장 빠른 방법: 개발자 모드

개발자 모드를 켜면 노션 하단의 개발자 바에 현재 보고 있는 페이지, 블록, 데이터베이스 또는 데이터 소스의 ID가 표시돼요. 블록이나 데이터베이스를 마우스 오른쪽 버튼으로 클릭하고 개발자 섹션을 열면 ID를 바로 복사할 수 있어요. 개발자 모드 설정과 마찬가지로 이 기능도 브라우저와 데스크톱 앱에서 사용할 수 있으며, 모바일에서는 사용할 수 없어요.

링크에서

공유 → 링크 복사로 페이지 링크를 복사하거나, 블록의 ⋮⋮ 메뉴에서 블록 링크 복사를 선택해 블록 링크를 복사하세요. 링크 유형마다 ID가 정해진 위치에 있어요:

Page
https://www.notion.so/acme/Launch-plan-1429989fe8ac4effbc8f57f56486db54

Database (full-page view)
https://www.notion.so/acme/248104cd477e80fdb757e945d38000bd?v=8f1c2a7e3b5d4c6e9a0b1c2d3e4f5a6b

Block
https://www.notion.so/acme/Launch-plan-1429989fe8ac4effbc8f57f56486db54#5c7d2e9a1b3f4c8d9e0f1a2b3c4d5e6f

2026년 6월부터 API 응답의 페이지 링크는 https://app.notion.com/p/… 형식을 사용해요. ID는 여전히 마지막 32자이며, 기존 notion.so 링크도 계속 작동해요.

두 가지 경우에 헷갈리기 쉬워요:

• 인라인 데이터베이스. 인라인 데이터베이스는 페이지 안에 있어 주소 표시줄에 해당 페이지의 ID가 표시돼요. 먼저 데이터베이스를 전체 페이지로 연 다음 링크를 복사하세요.
• 연결된 보기. 데이터베이스의 보기 메뉴에 원본 데이터베이스 열기가 있다면 연결된 보기를 보고 있는 거예요. API는 연결된 데이터베이스를 읽을 수 없어요. 원본을 열어 원본의 ID를 사용하고, 연결에 원본 접근 권한을 부여하세요.

데이터베이스에서 id()를 사용하는 수식 속성은 각 행의 페이지 ID를 하이픈 없이 표시하고, id(prop("Project").first())는 연결된 페이지의 ID를 반환해요. 자동화 도구에서 행 ID를 입력해야 할 때 유용해요.

링크에 없는 데이터 소스 ID

API 버전 2025-09-03부터 데이터베이스는 하나 이상의 데이터 소스를 담는 컨테이너예요. 속성과 행은 데이터 소스에 저장되므로, 데이터베이스의 행을 조회하거나 페이지를 만들 때는 /v1/data_sources/ 하위 엔드포인트를 사용해요. 이 엔드포인트에는 링크에 있는 데이터베이스 ID가 아니라 데이터 소스 ID가 필요해요. 데이터 소스 ID를 확인하는 방법은 세 가지예요:

• 노션에서: 데이터베이스의 설정 메뉴를 열고 데이터 소스 관리로 이동한 다음 데이터 소스 ID 복사를 클릭하세요. 개발자 모드가 켜져 있다면 데이터베이스를 마우스 오른쪽 버튼으로 클릭하는 방법도 사용할 수 있습니다.
• API에서: 데이터베이스를 조회하고 data_sources 목록을 확인하세요.
• 검색에서: 위에 나온 data_source 필터를 사용하세요.

curl https://api.notion.com/v1/databases/248104cd477e80fdb757e945d38000bd \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2026-03-11"

# the part of the response you need
{
  "object": "database",
  "id": "248104cd-477e-80fd-b757-e945d38000bd",
  "data_sources": [
    { "id": "248104cd-477e-80af-bc30-000bd28de8f9", "name": "Grocery list" }
  ]
}

그런 다음 POST /v1/data_sources/248104cd-477e-80af-bc30-000bd28de8f9/query로 행을 쿼리하세요. 현재 대부분의 데이터베이스에는 데이터 소스가 하나뿐이지만, 이를 전제로 구현하지는 마세요. 노션의 업그레이드 가이드에서는 누군가 데이터베이스에 두 번째 데이터 소스를 추가하면 이전 API 버전을 계속 사용하는 연결에서는 더 이상 해당 데이터베이스를 검색으로 찾을 수 없고, 해당 데이터베이스에 대한 읽기, 쓰기, 쿼리도 실패한다고 경고해요.

코드에서

공식 JavaScript SDK가 이 파싱을 대신 처리해 줘요. extractPageId, extractDatabaseId, extractBlockId는 2025년 9월에 추가됐어요. 이 함수들은 하이픈이 포함된 ID를 반환하고, 쿼리 매개변수의 ID보다 경로에 있는 ID를 우선하므로 데이터베이스 링크에서 실수로 보기 ID를 가져오는 일이 없어요.

import { extractDatabaseId } from "@notionhq/client";

extractDatabaseId("https://www.notion.so/acme/248104cd477e80fdb757e945d38000bd?v=8f1c2a7e3b5d4c6e9a0b1c2d3e4f5a6b");
// "248104cd-477e-80fd-b757-e945d38000bd"

처음 마주치는 오류부터 해결해요

오류 응답에는 HTTP 상태, code, 사람이 읽을 수 있는 message가 포함돼요. 다음 여섯 가지 오류 응답은 사용 첫날 발생할 수 있는 거의 모든 문제를 포괄해요.

오류처럼 보이지 않는 또 다른 문제 세 가지:

• 관계형 속성이 빈 값으로 반환돼요. 관련 데이터베이스도 해당 연결에 공유해 주세요. 공유하지 않으면 해당 관계를 기반으로 하는 속성이 응답에서 제외돼요. 데이터베이스 관계의 작동 방식은 노션 데이터베이스 관계 가이드에서 확인할 수 있어요.
• 검색 결과가 없어요. 토큰은 접근 권한이 있는 항목만 찾을 수 있어요. 연결의 경우, 해당 연결에 공유된 페이지와 그 하위 페이지가 여기에 해당해요.
• 어제는 성공한 요청이 오늘은 실패해요. PAT가 만료되었거나, 관리자가 이를 철회했거나, 누군가 연결의 토큰을 갱신했을 수 있어요. 내부 및 공개 연결의 경우, 개발자 도구의 상태 탭에서 지난 24시간 동안의 요청과 각 요청의 오류 코드, 요청 속도 제한에 걸린 내역을 확인할 수 있어요.

2026년 Notion API 요청 속도 제한

노션은 2026년 9월 9일에 요청 한도를 변경했어요. 이전 답변에서는 모든 플랜에 동일하게 초당 평균 3건의 요청 한도가 적용되고, 대기 시간이 최대 15분이라고 설명했어요. 이제는 플랜에 따라 한도가 다르고, 분 단위로 집계돼요. 노션의 요청 한도 페이지에서는 다음과 같이 안내하고 있어요.

연결별 요청 허용량은 60초마다 초기화되며, 한 번에 모두 사용할 수 있어요. 한도를 초과하면 노션은 HTTP 429, rate_limited 코드, 대기 시간을 초 단위로 표시하는 Retry-After 헤더를 반환해요. 연결별 한도에 따른 대기 시간은 60초를 넘지 않지만, 워크스페이스 공유 한도에 걸리면 더 오래 기다려야 할 수 있어요. 어떤 한도에 도달했는지는 additional_data.rate_limit_reason 필드에서 확인할 수 있어요. 529 service_overload는 노션 자체가 과부하 상태라는 뜻으로, 429와 동일하게 처리하세요. Notion MCP 도구 호출도 동일한 요청 허용량을 소모해요.

그 범위를 벗어나지 않는 방법:

1. 각자 독립적으로 재시도하는 병렬 워커 대신 하나의 큐를 통해 요청을 보내세요.
2. 429 또는 529 오류가 발생하면 Retry-After에 지정된 시간만큼 기다린 후 재시도하세요. 같은 오류가 다시 발생하면 약간의 무작위 지연을 더해 대기 시간을 지수적으로 늘리고, 시도 횟수에 상한을 두세요.
3. 대부분의 400 오류는 재시도하지 말고 요청을 수정하세요. 사유가 public_api_request_blocked인 429 오류도 기다린다고 해결되지 않으니 노션 지원팀에 문의하세요.
4. 503을 반환한 쓰기 작업을 다시 시도하기 전에 additional_data.retry_guidance를 확인하세요. 변경 사항이 이미 저장되었을 수 있으며, 이 경우 다시 시도하면 두 번 적용됩니다.

키를 안전하게 보관하세요

토큰을 가진 사람은 누구나 해당 토큰이 허용하는 모든 작업을 할 수 있어요. PAT의 경우 내가 열 수 있는 모든 항목이, 연결의 경우 해당 연결과 공유된 모든 페이지가 그 대상이에요.

• 토큰은 코드 외부에 보관하세요: 로컬 작업 시에는 환경 변수를 사용하고 .env를 .gitignore에 등록하세요. 프로덕션 환경에서는 시크릿 관리 도구를 사용하세요.
• 웹 페이지에는 절대 넣지 마세요. Notion API는 브라우저 코드에서 보내는 요청을 허용하므로, 다른 사람이 열 수 있는 페이지에 토큰을 삽입하면 소스를 보는 누구나 그 토큰을 사용할 수 있어요.
• 채팅, 지원 티켓, 이슈 트래커에 붙여 넣지 마세요. AI 어시스턴트와의 대화도 여기에 포함돼요.
• 도구와 환경의 조합마다 토큰을 하나씩 따로 사용하세요. 그래야 토큰 하나를 폐기해도 나머지는 정상적으로 작동해요.
• 권한은 최소한으로 부여하세요. 타사 도구에는 본인이 볼 수 있는 모든 콘텐츠를 볼 수 있는 PAT보다 공유한 페이지만 볼 수 있는 내부 연결을 사용하는 편이 더 안전해요. 실험용 PAT의 만료 기간은 짧게 설정하세요.
• 저장소와 CI에서 시크릿 검사를 활성화하세요. ntn_ 접두사는 검사 도구가 노션 토큰을 식별할 수 있도록 붙어 있어요.

토큰이 유출되면 다음 순서로 조치하세요. 노션에서 설정 → 연결 → 연결 개발 또는 관리를 열고 해당 연결이나 토큰을 찾은 다음, 내부 연결이라면 새로고침을 클릭하고 PAT라면 폐기하세요. 기존 값을 사용한 모든 곳에서 새 값으로 교체하세요. 그런 다음 페이지와 데이터베이스의 최근 변경 사항을 확인하고, 모르는 연결이 있는지 살펴보세요. 워크스페이스 관리자는 설정 → 연결에서도 어느 멤버의 PAT든 폐기할 수 있지만, 토큰 자체를 보거나 복사하는 것은 불가능합니다.

API 키가 필요 없는 경우

• AI 앱. Claude, ChatGPT, Cursor, Codex와 VS Code는 OAuth를 통해 노션에서 호스팅하는 MCP 서버에 연결되므로 키를 만들 필요가 없어요. 저희가 제공하는 Notion MCP 설정 도우미에서 앱별로 정확한 설정을 확인할 수 있어요. 예외는 두 가지예요. Business와 Enterprise에서는 워크스페이스 소유자가 로그인 창을 열 수 없는 클라이언트용 MCP 토큰을 만들 수 있어요. 또 오픈 소스 셀프 호스팅 MCP 서버는 API 토큰을 사용하지만, 노션은 더 이상 이 서버를 적극적으로 유지 관리하지 않아요.
• 노션 로그인을 사용하는 앱. 노션 창을 열고 페이지를 선택하도록 요청하는 도구는 공개 연결을 사용하며, 사용자에게 토큰이 표시되지 않아요.
• 워크스페이스의 연결 구조 확인. 관계를 직접 도식화하려고 페이지와 데이터베이스 ID를 모으는 경우가 많아요. IVGraph는 노션의 OAuth 창을 통해 연결하고, 모든 페이지와 멘션, 데이터베이스 관계를 인터랙티브 3D 그래프로 그려 줘요. 노드 500개까지 무료로 사용할 수 있어요.

에이전트가 해당 그래프를 읽어야 한다면, IVGraph의 Pro 및 Max 요금제에서 전용 서비스 토큰이 있는 읽기 전용 에이전트용 API를 사용할 수 있어요. 검색, 페이지 콘텐츠, 인접 페이지, 페이지 간 경로를 제공해요. IVGraph MCP 서버는 아직 없어요.

자주 묻는 질문