Notion API Key 怎麼拿？Integration Token 申請、資料庫授權與 curl 測試 4 步搞定（2026）

解答先行

Notion API Key 怎麼拿？ 登入 Notion Developer Portal，建立一個 internal connection / integration，系統會給你一組以 ntn_ 開頭的 Integration Token。這組 token 就是多數人搜尋時說的「Notion API Key」。

拿到 token 後還不能直接讀所有資料。你還要到目標 page、database 或 data source 右上角按 Add connections，把資料授權給這個 integration，API 才讀得到。

如果你現在只想跑通，最短路徑是這 4 步：

先把這四步跑通，再去想 n8n、WordPress、自動化、SDK，成功率會高很多。

如果你只想快速判斷自己要拿哪一種 token，先看這張表：

這就是最短答案。下面把每一步拆開講，並附 curl 測試與常見錯誤排查。

很多人搜尋 notion api、notion api key、notion api token，多半只是想趕快拿到 token，讓外部工具可以讀寫 Notion，還沒有要研究 API 本身。

如果你已經拿到 token，只想直接測 endpoint，可以接著看子文：Notion API 用 curl 測試教學：5 個最常用 endpoint 速查。

真正想做的通常是這幾件事：

• Typeform 表單填完，自動寫進 Notion
• n8n 抓資料後，更新 Notion 任務狀態
• 本地 Markdown 草稿同步到 Notion
• Notion 文章同步到 WordPress
• AI 產文後，把結果寫回 Notion database
• 客戶、專案、內容排程可以自動更新

也就是說，你不是為了炫技才需要 Notion API。

你需要它，是因為 Notion 已經變成你的資料中心，但資料不可能永遠只靠手動複製貼上。

為什麼要用 Notion API？

Notion 最好用的地方，是 database。

你可以把文章、任務、客戶、專案、靈感、會議紀錄都放進資料庫，然後用不同 View 管理。但只要你開始經營網站、社群、自動化流程，就會遇到一個問題：

Notion 裡的資料很好整理，但外部工具不會自己知道。

例如：

• 你在 Notion 寫完文章，WordPress 不會自己更新
• 你在 Typeform 收到表單，Notion 不會自己新增一筆資料
• 你在 n8n 跑完流程，Notion 不會自己改狀態
• 你讓 AI 生成社群貼文，Notion 不會自己存版本

這時候 Notion API 的角色就出現了。

它讓外部工具可以用一套標準方式讀取、建立、更新 Notion 裡的資料。

所以我會把 Notion API 定位成：

讓 Notion 從「好用的工作區」變成「可以被其他工具讀寫的資料中心」。

如果你只是自己做筆記，不一定需要 API。
但如果你想把 Notion 接進網站、AI、自動化、CRM、內容系統，那 API 就是一定會碰到的路。

Notion API 是什麼？

API 可以先理解成「軟體之間溝通的標準語言」。

在 Notion API 裡，最常見的流程是：

1. 你用 token 證明自己有權限
2. 你告訴 Notion 想讀哪個頁面、資料庫或 data source
3. Notion 回傳 JSON
4. 你的程式再決定要新增、更新或同步到其他地方

Notion API 是 REST API。請求會送到：

https://api.notion.com

每次呼叫通常會需要三個重點 header：

Authorization: Bearer YOUR_TOKEN
Notion-Version: 2026-03-11
Content-Type: application/json

新手最常卡住的不是 API 太難，而是沒有搞懂這三層：

只要你能分清楚是哪一層出錯，Notion API 其實沒有想像中難。

Notion API Key、Token、Integration Token、PAT 差在哪？

很多教學會混用這些詞：

• Notion API Key
• Notion API Token
• Notion Integration Token
• Notion Secret Key
• Notion Access Token
• Personal Access Token

新手可以先這樣理解：

Notion 官方現在把整合分成幾種常見路線：

1. Internal connection：單一 workspace 內部用，適合自己的自動化。
2. Public connection：用 OAuth，適合做給別人安裝的公開工具。
3. Personal Access Token, PAT：用某個使用者的權限呼叫 API，適合腳本、CLI、CI。

如果你只是要做自己的 Notion 自動化，先從 internal connection 開始就好。

Notion API Key 取得：4 步驟跑完

如果你現在只想拿到 notion api key，照這個順序做：

這 4 步缺一個都會出事。

很多人卡在第 3 步：token 已經拿到了，但目標 database 沒有授權給 connection。這時候你用 API 查資料，就會看到 403、object not found，或 search 找不到任何內容。

我會建議你先不要急著接 n8n 或寫正式腳本。先讓這兩個 request 成功：

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

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" \
  --data '{}'

第一個測 token，第二個測授權範圍。兩個都通，再往下做正式自動化。

Notion API Key 格式長怎樣？

現在很多新整合拿到的 token 會以 ntn_ 開頭。舊教學可能會寫 secret_，所以你看到不同格式不用先慌。

重點不是前綴，而是這三件事：

如果你是在 n8n 或其他工具看到 NOTION_API_KEY、NOTION_API_TOKEN、NOTION_ACCESS_TOKEN，多半只是環境變數名稱不同。真正放進去的值，通常都是 Notion Developer Portal 產生的 token。

SDK 是什麼？一定要用 SDK 嗎？

SDK 可以理解成「官方幫你包好的工具包」。

你可以直接用 curl 或 fetch 呼叫 Notion API，也可以用 Notion 的 JavaScript SDK。SDK 的好處是，它幫你處理一些重複設定，讓程式碼比較乾淨。

例如你可以這樣初始化：

const { Client } = require("@notionhq/client");

const notion = new Client({
  auth: process.env.NOTION_ACCESS_TOKEN,
});

但新手不一定要一開始就用 SDK。

我會建議順序是：

1. 先用 curl 測 token 和權限
2. 確認 API 能通
3. 再改用 SDK 寫正式流程

原因很簡單：curl 比較接近底層。你可以清楚看到 header、endpoint、payload。當你連 curl 都打不通時，直接上 SDK 只會讓錯誤更難判斷。

Notion API 可以拿來做什麼？

Notion API 最適合拿來做「資料流」。

你可以把 Notion 當成資料來源，也可以把 Notion 當成資料目的地。

如果你只是偶爾整理資料，可能手動就好。

但如果你每週都在做同一件事，例如「文章寫完、複製到 WordPress、再回 Notion 改狀態」，那就很適合用 API。

延伸可以看：

• Notion 社群貼文工作流
• Notion 自動化完整教學
• Notion 整合 Metricool 教學

我拿這把 key 實際在做的自動化

這個站每天都在跑 Notion API，用的就是這篇教你拿的那種 internal connection token。三條流程：

1. 文章同步：SEO 文章在本地用 Markdown 寫，寫完由腳本透過 API 建立或更新 Notion 寫作資料庫的對應頁面，兩邊內容保持一致。
2. 社群發佈：Threads 與其他平台的貼文草稿放在 Notion 社群資料庫，發佈腳本讀出內容發到平台，再回寫發佈狀態與貼文連結。
3. 狀態回寫：每次同步或發佈完成，腳本會更新對應欄位（Status、已發佈勾選、URL），資料庫自己保持最新，我不用手動對帳。

這三條用的都是同一把 token。你不需要 OAuth，也不需要做公開 app，一個 internal connection 就足夠跑起一條內容生產線。

如何取得 Notion API Key（Integration Token）？

下面用新手最常用的 internal connection 來說。

步驟 1：進入 Notion Developer / Integrations

到 Notion 的 Developer portal 或 workspace 的 integration 設定，建立一個新的 internal connection。

你可以幫它取一個好懂的名字，例如：

• WordPress Sync
• n8n Automation
• Content Pipeline
• Local Script

名字不要亂取，因為之後你在 Notion 裡授權頁面或 database 時，會需要認出它。

步驟 2：取得 token

建立完成後，你會看到這個 connection 對應的 token。這組 token 官方稱作 internal integration token，多數工具設定欄裡要你填的「Notion API Key」或「Notion Token」，指的都是它。

請把它存進安全位置，例如：

export NOTION_ACCESS_TOKEN="你的 token"

不要把 token 貼到：

• 前端程式碼
• 公開 GitHub repo
• 截圖
• 文章範例
• 可以被外部下載的設定檔

Token 就是密碼。拿到 token 的人，有機會讀寫你授權給它的 Notion 內容。

步驟 3：把資料庫或頁面授權給 connection

這是最多人漏掉的一步。

拿到 token 只代表你有鑰匙，不代表你可以開所有門。

你還要回到 Notion，把目標 page、database 或 data source 授權給這個 connection。

常見位置是頁面右上角的：

Connections / Add connections

如果這一步沒做，最常看到的錯誤就是：

403 forbidden

步驟 4：用 curl 驗證 token 與授權

前三步做完，不要急著把 token 貼進 n8n 或正式腳本。先用兩個最簡單的 request 驗證：打 GET /v1/users/me 確認 token 有效，再打 POST /v1/search 確認授權範圍讀得到資料。

兩個都通，這組 Notion API Key 才算真的能用。完整指令與 401 / 403 判讀，往下看「用 curl 測試 Notion API」段，或直接看子文 Notion API 用 curl 測試教學：5 個最常用 endpoint 速查。

用 curl 測試 Notion API

第一次測試，我不建議直接打最複雜的 database query。

先測 token 是否有效。

測試 1：確認 token 能用

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

如果這一步成功，代表：

• token 格式基本正確
• Authorization header 沒寫錯
• Notion-Version 有帶

如果這一步都回 401，先不要急著查 database。你現在還在 token 層。

測試 2：用 search 找資料

curl -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer $NOTION_ACCESS_TOKEN" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  --data '{}'

如果 search 能回資料，代表 API 基本能讀到你授權範圍內的內容。

如果你知道關鍵字，也可以加 query：

curl -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer $NOTION_ACCESS_TOKEN" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  --data '{"query":"content"}'

測試 3：讀取 data source

現在 Notion 文件裡，資料庫相關操作會越來越常看到 data source 的概念。

如果你要查詢某個 data source，可以用：

curl -X POST "https://api.notion.com/v1/data_sources/YOUR_DATA_SOURCE_ID/query" \
  -H "Authorization: Bearer $NOTION_ACCESS_TOKEN" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  --data '{}'

新手先不要硬背 ID。

我會建議先用 search 找到目標，再確認自己拿的是對的 data source id。很多舊教學會拿 page id 或 database id，照抄時很容易錯。

Notion API 最常見錯誤怎麼排查？

先看 status code，不要一開始就重寫程式。

我自己的排查順序固定是：

1. 先測 GET /v1/users/me
2. 再測 POST /v1/search
3. 確認目標內容有 Add connections
4. 再測 data source query
5. 最後才處理 properties payload

這樣你不會把授權問題誤判成程式碼問題。

Notion API 和 n8n、Make、Zapier 怎麼選？

不一定要一開始就寫程式。

如果你只是想先驗證流程，可以先用 n8n、Make、Zapier、Typeform 這類工具。等你確定資料流真的有價值，再用 API 寫得更穩。

如果你是新手，我會建議：

先 no-code 跑通，再用 API 重做核心流程。

這比一開始就寫完整自動化更穩。

MCP、CLI、API 要怎麼選？

現在 Notion 生態裡不只 API。你還可能看到 MCP、CLI、PAT。

簡單分工：

如果你要做「自動化生產線」，還是以 API 為主。

如果你只是想讓 AI 幫你查 Notion 筆記，MCP 會比較自然。

Notion API 速率限制與安全注意

Notion API 有 rate limit。官方常見建議是以平均每秒 3 個 request 當作保守上限來設計。

實務上你要做三件事：

1. 不要在迴圈裡無限制狂打 API
2. 遇到 429 要 retry，而不是直接失敗
3. 批次同步要做 checkpoint，避免中斷後全部重跑

安全上也很簡單：

• token 放環境變數
• CI/CD 用 secrets
• 不要放前端
• 不要 commit 到 GitHub
• 不同環境用不同 token
• 不用的 token 要 revoke

我會怎麼建議新手開始？

如果你今天是第一次碰 Notion API，我會照這個順序：

1. 建一個測試 database
2. 建一個 internal connection
3. 拿 token
4. 把測試 database Add connections 給它
5. 用 GET /v1/users/me 測 token
6. 用 POST /v1/search 測授權範圍
7. 用 data source query 讀資料
8. 再決定要接 n8n、WordPress、AI 或自己的腳本

不要一開始就把正式資料庫拿來測，也不要一開始就寫很大。

先讓第一個 request 成功。
Notion API 的學習曲線，大部分就卡在這一步。

延伸閱讀

• Notion Database 教學：資料庫完整入門
• Notion Workspace 教學：工作區建立與設定
• Notion 自動化完整教學
• Notion 社群貼文工作流
• Notion 備份完整教學

常見問題 FAQ

Notion API Key 要去哪裡拿？

到 Notion Developer portal 建立 internal connection / integration 後，就可以取得 token。取得後仍要把目標 page、database 或 data source 授權給這個 connection，否則常見 403。

Notion Integration Token 在哪裡？

在 Notion Developer Portal 的 connection / integration 設定頁裡。建立 internal connection 後，通常會看到一組 secret 或 internal integration token；複製後請放在環境變數，不要貼進前端程式碼或公開 repo。

Notion API Token 跟 Notion API Key 是同一個東西嗎？

多數搜尋情境下可以先當成同一件事理解。比較準確的說法是 token 或 integration token；API Key 通常只是大家搜尋時的叫法。

Notion API Key 格式一定是 secret_ 開頭嗎？

不一定。新整合常見的是 ntn_ 開頭；舊教學可能會提到 secret_。不要只用前綴判斷對錯，重點是 token 是否從 Notion Developer Portal 取得、是否完整複製、是否用 Authorization: Bearer 帶入。

Notion Integration Token 和 PAT 差在哪？

Integration Token 通常用在某個 connection / integration；PAT 是 personal access token，會以某個使用者在 workspace 裡的權限呼叫 API。內部自動化先用 internal connection 就好。

為什麼我拿到 token 還是 403？

因為 token 只是憑證，不代表自動擁有所有資料權限。你要把目標頁面、database 或 data source 透過 Add connections 授權給這個 connection。

Notion Database 要怎麼授權給 API？

打開目標 database 或所在頁面，從右上角選單找到 connections / Add connections，把你建立的 Notion integration 加進去。只拿到 token 沒授權 database，API 還是會回 403 或搜尋不到資料。

Notion API 新手第一個 curl 應該打哪個？

先打 GET /v1/users/me 測 token，再打 POST /v1/search 測授權範圍。不要一開始就打最複雜的 data source query。

Data Source ID 要怎麼找？

建議先用 POST /v1/search 找到目標內容，再確認你拿的是正確 data source。不要直接照抄舊教學裡從網址截出來的 ID。

SDK 是什麼？一定要用嗎？

SDK 是官方或工具方包好的開發工具包，像 Notion JavaScript SDK。它可以讓程式碼比較乾淨，但新手建議先用 curl 打通，再改用 SDK。

Notion API 免費嗎？

Notion API 本身不另外收費，但你能不能使用某些 Notion 功能，仍取決於你的 Notion 帳號方案、workspace 設定與權限。

Notion API 可以和 n8n 一起用嗎？

可以。新手可以先用 n8n 的 Notion node 跑通流程，等流程穩定後，再把核心部分改成 API 腳本。

Notion API Token 要怎麼保存才安全？

請放環境變數或 secrets manager，不要放在公開 repo、前端程式碼、文章截圖或可被外部下載的設定檔。

參考資料

資料最後查核日期：2026-05-17

• Notion Developers: Authentication：https://developers.notion.com/reference/authentication
• Notion Developers: Introduction：https://developers.notion.com/reference
• Notion Developers: Getting started overview：https://developers.notion.com/guides/get-started/overview
• Notion Developers: Personal access tokens：https://developers.notion.com/guides/get-started/personal-access-tokens
• Notion Developers: Working with databases：https://developers.notion.com/guides/data-apis/working-with-databases