如何取得 Notion API 金鑰，並找出請求所需的 ID

Notion API 金鑰是你的程式碼每次向 Notion API 傳送請求時都會附上的權杖。2026 年共有三種類型：代表你本人操作的個人存取權杖、用於團隊自動化作業的內部連線權杖，以及供他人安裝的應用程式使用的 OAuth。以下將說明如何建立這三種類型的憑證、授予這些憑證存取你頁面的權限、找出請求所需的頁面、資料庫與資料來源 ID，以及排除幾乎所有人初次嘗試時都會遇到的錯誤。

你需要哪種 Notion API 金鑰？

Notion 的開發者文件列出三種身分驗證方式，差別在於權杖代表誰的權限、能查看哪些內容，以及誰有權建立權杖。

快速選擇的方法：

• 只有你自己使用的指令碼、筆記本或工具：使用個人存取權杖。不必分享任何內容，兩分鐘就能開始使用。
• 團隊仰賴的自動化流程：使用內部連線。即使設定者離職，仍能持續運作，而且只能存取你分享給它的頁面。
• 供他人安裝的應用程式：使用搭配 OAuth 的公開連線。絕不要要求使用者貼上權杖。
• Claude、ChatGPT、Cursor 或其他 AI 應用程式：通常完全不需要金鑰。Notion 託管的 MCP 伺服器會透過 OAuth 讓你登入；我們的 Notion MCP 指南說明了設定方式。

選項 1：建立個人存取權杖

個人存取權杖（PAT）會以你的身分運作，具有你的工作空間成員資格與頁面權限。Notion 官方的 API 快速入門指南也是從個人存取權杖開始，因為除了權杖之外，不需要進行其他設定。

1. 開啟開發人員模式。在 Notion 中開啟設定，搜尋開發人員模式並開啟。這是本機設定：瀏覽器和桌面應用程式都需要分別開啟，行動裝置則不提供此功能。
2. 開啟權杖清單。側邊欄會出現開發人員專區。開啟個人存取權杖，然後點選新增權杖。也可以透過此連結直接前往：notion.so/developers/tokens。
3. 命名並設定存取範圍。選擇 Notion API 功能（只有在部署 Notion Workers 時才需加入 Workers），並設定有效期限：7、30、90 或 180 天，或預設的 1 年。如果出現工作空間選擇器，請選擇工作空間：每個權杖只屬於一個工作空間。
4. 點選「建立權杖」，並立即複製權杖值。Notion 只會顯示一次，之後就無法再次查看，連管理員也不例外。請將權杖存放在密碼管理工具或專案的機密儲存庫中。

新權杖以 ntn_ 開頭。Notion 於 2024 年 9 月 25 日起不再使用 secret_ 前綴，改用新前綴，舊權杖仍可繼續使用。不過，請勿在程式碼中檢查前綴：Notion 表示格式可能會變更，並要求開發者將權杖視為不透明字串處理。

無法建立權杖？

訪客和受限成員完全無法建立 PAT。至於其他成員，則由方案決定誰可以建立具有 Notion API 存取權的 PAT：

使用 Business 和 Enterprise 方案時，請工作空間擁有者前往設定 → 連線允許此連線。如果管理員之後限縮政策，現有的權杖就會失效，並傳回 unauthorized。

PAT 可存取的範圍

你在該工作空間中能開啟的所有內容：頁面、資料庫、留言和檔案。頁面不必另外分享給它。這讓 PAT 能快速投入使用，也讓 PAT 洩漏的代價高昂。Notion 的文件並未提及唯讀的 PAT：Notion API 功能可讀取、建立及更新內容。如果某項工作只需要讀取少數幾個頁面，僅具備讀取內容權限的內部連線會是較安全的金鑰選擇。當你失去某個頁面的存取權或離開工作空間時，權杖也會失去相應的存取權。

選項 2：建立內部連線權杖

內部連線是隸屬於單一工作空間的機器人使用者。請將其用於團隊仰賴的自動化流程，或任何只應存取少數頁面、而非你能開啟的所有內容的工具。舊版指南稱它為「內部整合」，並將其權杖稱為「內部整合密鑰」或「整合權杖」。

1. 確認你是工作空間擁有者。只有擁有者才能建立連線。如果你不是擁有者，可以請擁有者協助，或依照 Notion 常見問題的建議，建立免費的個人工作空間來試用。
2. 建立連線。在側邊欄的開發人員區塊，或前往 notion.so/developers，開啟內部連線，點選建立新連線，輸入名稱並選擇工作空間。連線建立後無法移至其他工作空間；若要在其他工作空間使用，必須在該處建立新的連線。
3. 複製 API 權杖。開啟連線的設定分頁，複製 API 權杖。擁有者也可以從設定 → 連線取得權杖：連線旁的 ••• 選單中有取得權杖的選項。
4. 在同一個分頁中設定功能權限（清單如下）。
5. 授予頁面存取權。新連線無法看到任何內容，在你分享內容之前，所有請求都會失敗。在內容存取權分頁中，點選編輯存取權，選取頁面和資料庫。你也可以在 Notion 中開啟頁面，點選右上角的 •••，找到連線，選擇新增連線，再搜尋你建立的連線。分享頁面時，也會一併分享其子頁面。

權限範圍會限制權杖可執行的操作，即使在權杖可檢視的頁面上也一樣。Notion 文件建議只申請最低限度的權限：

• 讀取內容、更新內容、新增內容，可任意組合。匯出只需要讀取內容的權限。新增資料列的表單只需要新增內容的權限。設定狀態的指令碼只需要更新內容的權限。
• 讀取留言、新增留言。
• 使用者資訊：不提供、不含電子郵件地址，或包含電子郵件地址。

由於連線本身就是獨立的使用者，其存取權限不取決於個別人員。即使分享頁面的團隊成員離開工作空間，連線仍可存取該頁面。每位工作空間擁有者都能查看所有內部連線，包括其他人建立的連線。

選項 3：為供他人使用的應用程式採用 OAuth

如果你正在開發產品，別要求使用者貼上權杖。請改為建立公開連線：每位使用者透過 Notion 的 OAuth 視窗登入，並選擇允許你的應用程式查看的頁面。在你掌控的伺服器上，將 OAuth 授權碼換成權杖。用戶端密鑰絕不能傳到瀏覽器，而 Notion 的 OAuth 權杖端點也刻意不開放給瀏覽器端程式碼存取。IVGraph 就是透過這種方式連線：你只需在 Notion 視窗中選擇頁面，完全不必經手金鑰。

傳送一次請求，測試金鑰

請將權杖存放在環境變數中，而非程式碼裡。在 macOS 或 Linux 上：

export NOTION_API_KEY="ntn_…"

在 Windows PowerShell 中，請使用 $env:NOTION_API_KEY = "ntn_…"。接著向 Notion 查詢這個權杖屬於誰：

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 只需設定一次權杖，就會自動重試受到速率限制的請求。目前版本的 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

Notion 中的每個頁面、資料庫和區塊都有一個 ID，也就是由 32 個十六進位字元組成的 UUID。連結中的 ID 不含連字號，而 API 則接受含有或不含連字號的格式。加上連字號時，字元會依 8-4-4-4-12 分組，因此 1429989fe8ac4effbc8f57f56486db54 會變成 1429989f-e8ac-4eff-bc8f-57f56486db54。

最快的方式：開發人員模式

開啟開發人員模式後，Notion 底部的開發人員列會顯示目前查看的頁面、區塊、資料庫或資料來源的 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 有三種方式：

• 在 Notion 中：開啟資料庫的設定選單，前往管理資料來源，然後點選複製資料來源 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 查詢資料列。目前大多數資料庫都只有一個資料來源，但建置時別以此為前提。Notion 的升級指南提醒，一旦有人在資料庫中新增第二個資料來源，仍使用舊版 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。以下六種錯誤涵蓋了使用第一天會遇到的幾乎所有問題：

還有三個看起來不像錯誤的問題：

• 關聯屬性傳回空值。也請將關聯的資料庫分享給該連線，否則回應中就不會包含以該關聯為基礎的屬性。關聯的運作方式，請參閱我們的Notion 關聯指南。
• 搜尋沒有結果。權杖只能找到其有權存取的內容。對連線來說，就是已分享給該連線的頁面及其子頁面。
• 昨天還成功的請求，今天卻失敗了。PAT 可能已過期、遭管理員撤銷，或有人更新了連線的權杖。針對內部與公開連線，開發人員工具中的健康狀態分頁會列出最近 24 小時的請求，以及各請求的錯誤代碼和觸及速率限制的情況。

2026 年 Notion API 速率限制

Notion 於 2026 年 9 月 9 日調整了請求限制。較早的解答提到，所有方案一律平均每秒可發出三次請求，等待時間最長可達 15 分鐘。現在，限制依方案而異，並以每分鐘為單位計算。以下是 Notion 請求限制頁面的說明：

每個連線的配額每 60 秒重設一次，也可以一次用完。超過限制時，Notion 會回傳 HTTP 429、rate_limited 代碼，以及以秒為單位的 Retry-After 標頭。若觸及每個連線的限制，等待時間不會超過 60 秒；若觸及工作空間共用的限制，則可能需要等待更久。additional_data.rate_limit_reason 欄位會指出你觸及哪一項限制。529 service_overload 表示 Notion 本身正忙碌，請比照 429 處理。Notion MCP 工具呼叫也會計入相同的限制。

如何不超出這些限制：

1. 透過單一佇列傳送請求，不要讓多個平行執行的工作程序各自重試。
2. 遇到 429 或 529 時，依 Retry-After 指定的時間等待後再重試。如果再次發生，請以指數退避方式延長等待時間，加入少量隨機延遲，並設定嘗試次數上限。
3. 大多數 400 錯誤不應重試，請修正請求。原因為 public_api_request_blocked 的 429 錯誤也不會因等待而解除；請聯絡 Notion 支援團隊。
4. 對傳回 503 的寫入操作進行重試前，請先讀取 additional_data.retry_guidance。變更可能已經儲存，重試會讓同一項變更套用兩次。

妥善保管金鑰

任何持有權杖的人都能執行該權杖允許的所有操作。若是 PAT，範圍涵蓋你能開啟的所有內容；若是連線，則涵蓋所有與該連線共用的頁面。

• 將權杖存放在程式碼之外：本機開發時使用環境變數，並將 .env 列入 .gitignore；正式環境則使用機密管理工具。
• 絕對不要將權杖放進網頁。Notion API 接受來自瀏覽器端程式碼的請求，因此，只要權杖嵌入在他人可開啟的頁面中，任何檢視原始碼的人都能使用它。
• 不要將權杖貼到聊天、客服工單或問題追蹤系統中，這也包括與 AI 助理的對話。
• 每個工具、每個環境都使用獨立的權杖，如此一來，撤銷其中一個權杖就不會影響其他工具與環境的運作。
• 只授予最低限度的權限。對第三方工具而言，只能存取你所分享頁面的內部連線，比能存取你所有可存取內容的 PAT 更安全。請為實驗用的 PAT 設定較短的有效期限。
• 在儲存庫和 CI 中啟用機密掃描。ntn_ 前綴的用途，就是讓掃描工具能辨識 Notion 權杖。

如果權杖外洩，請依下列順序處理。在 Notion 中開啟設定 → 連接 → 開發或管理連接，找到該連接或權杖，若是內部連接，請點選重新整理；若是 PAT，則將其撤銷。在所有使用舊權杖的地方換上新值。接著，檢查頁面和資料庫的近期變更，並確認是否有不認識的連接。工作空間管理員也可以從設定 → 連接撤銷任何成員的 PAT，但管理員始終無法查看或複製權杖本身。

何時不需要 API 金鑰

• AI 應用程式。Claude、ChatGPT、Cursor、Codex 和 VS Code 透過 OAuth 連線至 Notion 託管的 MCP 伺服器，因此不需要建立金鑰。我們的 Notion MCP 設定助手會提供各應用程式所需的確切設定。有兩種例外情況：在 Business 和 Enterprise 方案中，工作空間擁有者可以為無法開啟登入視窗的用戶端建立 MCP 權杖；而開源、自行託管的 MCP 伺服器則使用 API 權杖，不過 Notion 已不再積極維護該伺服器。
• 使用 Notion 登入的應用程式。如果工具會開啟 Notion 的視窗並請你選取頁面，就表示它使用公開連線，過程中你不會看到任何權杖。
• 瞭解工作空間中的連結關係。許多人會蒐集頁面和資料庫的 ID，手動繪製關聯圖。IVGraph 透過 Notion 的 OAuth 視窗連線，將每個頁面、提及和資料庫關聯繪製成互動式 3D 圖譜。500 個節點以內可免費使用。

如果需要讓代理讀取這個圖譜，IVGraph 的 Pro 和 Max 方案提供唯讀的代理專用 API，搭配專屬的服務權杖，可搜尋、讀取頁面內容、查詢相鄰節點及頁面之間的路徑。目前尚無 IVGraph MCP 伺服器。

常見問題