Notion APIキーの取得方法とリクエストに必要なIDの確認方法

Notion APIキーは、コードがNotionのAPIにリクエストを送るたびに含めるトークンです。2026年時点では、あなたの権限で動作するパーソナルアクセストークン、チームの自動化に使う内部接続トークン、ほかのユーザーがインストールするアプリ向けのOAuthという3種類があります。以下では、それぞれの作成方法、ページへのアクセス権の付与方法、リクエストに必要なページID・データベースID・データソースIDの調べ方、そして初回にほぼ誰もが遭遇するエラーの解決方法を説明します。

どのNotion APIキーが必要ですか？

Notionの開発者向けドキュメントでは、3つの認証方法が紹介されています。それぞれ、トークンに誰の権限が付与されるか、何にアクセスできるか、誰が作成できるかが異なります。

手早く選ぶには：

• 自分だけが使うスクリプト、ノートブック、ツール：個人アクセストークンを使います。共有は不要で、2分で使い始められます。
• チームの業務を支える自動化：内部接続を使います。設定した人がチームを離れても動作し続け、アクセスできるのはその接続に共有したページだけです。
• ほかの人がインストールするアプリ：OAuthによる公開接続を使います。ユーザーにトークンの貼り付けを求めてはいけません。
• Claude、ChatGPT、CursorなどのAIアプリ：通常、キーは一切不要です。NotionがホストするMCPサーバーではOAuthでログインできます。設定方法はNotion MCPガイドで解説しています。

方法1：個人アクセストークンを作成する

個人アクセストークン（PAT）は、あなたのワークスペースでのメンバーシップとページへのアクセス権限に基づき、あなたに代わって動作します。Notion公式のAPIクイックスタートも、トークン以外に設定するものがないため、PATを使うところから始まります。

1. 開発者モードを有効にします。 Notionで設定を開き、開発者モードを検索してオンにします。これはローカル設定のため、ブラウザーとデスクトップアプリでそれぞれ有効にする必要があります。モバイルでは利用できません。
2. トークン一覧を開きます。 サイドバーに開発者向けのセクションが表示されます。パーソナルアクセストークンを開き、新しいトークンをクリックします。notion.so/developers/tokensから直接アクセスすることもできます。
3. 名前とアクセス範囲を設定します。 機能としてNotion APIを選択し（Notion Workersをデプロイする場合のみWorkersも追加します）、有効期限を7日、30日、90日、180日、または初期設定の1年から選びます。ワークスペースの選択画面が表示された場合は、ワークスペースを選択します。1つのトークンは1つのワークスペースに紐づきます。
4. 「トークンを作成」をクリックし、すぐに値をコピーします。 Notionでトークンが表示されるのは一度だけです。管理者であっても再表示はできません。パスワードマネージャーまたはプロジェクトのシークレットストアに保存してください。

新しいトークンはntn_で始まります。Notionは2024年9月25日にsecret_から切り替えましたが、以前のトークンも引き続き使用できます。ただし、コード内で接頭辞をチェックしないでください。Notionは、形式が変更される可能性があると説明し、トークンの内容や構造を解釈せず、単なる文字列として扱うよう開発者に求めています。

トークンを作成できませんか？

ゲストと制限付きメンバーは、PATを一切作成できません。それ以外のメンバーについては、Notion APIへのアクセス権を持つPATを作成できる人がプランによって決まります。

BusinessおよびEnterpriseでは、ワークスペースのオーナーに設定 → コネクトで許可するよう依頼してください。後から管理者がポリシーの許可範囲を狭めると、取得済みのトークンは使えなくなり、unauthorizedが返されます。

PATでアクセスできる範囲

そのワークスペース内であなたが開けるものすべて、つまりページ、データベース、コメント、ファイルにアクセスできます。PATにページを個別に共有する必要はありません。これがPATをすぐに使える理由であり、同時に、PATが漏えいした際の代償が大きくなる理由でもあります。Notionのドキュメントには、読み取り専用のPATについての記載はありません。Notion APIの権限には、読み取り、作成、更新が含まれます。数ページを読み取るだけの処理なら、コンテンツを読み取るのみを許可した内部コネクションのキーのほうが安全です。あなたがページへのアクセス権を失ったり、ワークスペースから退出したりすると、トークンも同じアクセス権を失います。

方法2：内部接続トークンを作成

内部接続は、1つのワークスペースに所属するボットユーザーです。チームが頼りにする自動化や、自分が開けるすべてのページではなく、少数のページだけにアクセスさせたいツールに使用します。古いガイドでは、内部接続は「内部インテグレーション」、そのトークンは「内部インテグレーションシークレット」または「インテグレーショントークン」と呼ばれています。

1. ワークスペースのオーナーであることを確認します。 コネクトを作成できるのはオーナーだけです。オーナーでない場合は、オーナーに依頼するか、NotionのFAQで案内されているように、無料の個人用ワークスペースを作成して試してください。
2. コネクトを作成します。 サイドバーの開発者向けセクション、またはnotion.so/developersで、内部コネクトを開き、新しいコネクトを作成をクリックして、名前を入力し、ワークスペースを選択します。作成したコネクトを後から別のワークスペースに移すことはできません。別のワークスペースで使う場合は、そこで新しく作成する必要があります。
3. APIトークンをコピーします。 コネクトの設定タブを開き、APIトークンをコピーします。オーナーは設定 → コネクトからも取得できます。コネクトの横にある•••メニューに、トークンを取得する項目があります。
4. 同じタブで権限を設定します（一覧は下にあります）。
5. ページへのアクセスを許可します。 新しいコネクトは何にもアクセスできず、何かを共有するまではすべてのリクエストが失敗します。コンテンツへのアクセスタブでアクセスを編集をクリックし、ページとデータベースを選択します。または、Notionでページを開き、右上の•••をクリックしてコネクトを見つけ、コネクトを追加を選択し、作成したコネクトを検索します。ページを共有すると、その子ページも共有されます。

トークンが閲覧できるページでも、実行できる操作は権限によって制限されます。Notionのドキュメントでは、必要最小限の権限をリクエストすることを推奨しています。

• コンテンツの読み取り、コンテンツの更新、コンテンツの挿入は、自由に組み合わせられます。エクスポートには「コンテンツの読み取り」のみ、行を追加するフォームには「コンテンツの挿入」のみ、ステータスを設定するスクリプトには「コンテンツの更新」のみが必要です。
• コメントの読み取り、コメントの挿入。
• ユーザー情報：取得しない、メールアドレスを含めずに取得する、メールアドレスを含めて取得するのいずれかを選べます。

接続自体が独立したユーザーであるため、アクセス権は個人に依存しません。ページを共有したチームメンバーがワークスペースを離れても、接続はそのページへのアクセス権を保持します。ワークスペースのすべてのオーナーは、他のメンバーが作成したものも含め、すべての内部接続を確認できます。

方法3：他の人が使うアプリ向けのOAuth

プロダクトを開発するなら、ユーザーにトークンの貼り付けを求めるのではなく、パブリックコネクションを作成しましょう。各ユーザーがNotionのOAuthウィンドウでサインインし、アプリに閲覧を許可するページを選びます。OAuthコードをトークンに交換する処理は、自分で管理するサーバー上で行ってください。クライアントシークレットをブラウザーに渡してはいけません。また、NotionのOAuthトークンエンドポイントは、ブラウザー上で実行されるコードから意図的にアクセスできないようになっています。IVGraphもこの方式で接続します。Notionのウィンドウでページを選ぶだけで、キーを扱う必要は一切ありません。

1回のリクエストでキーをテストする

トークンはコード内ではなく、環境変数に保存してください。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 では、トークンを一度設定するだけで、レート制限にかかったリクエストが自動的に再試行されます。現在のリリースではデフォルトで 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のすべてのページ、データベース、ブロックには、32桁の16進数で表される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リンクもそのまま使えます。

つまずきやすいのは、次の2つのケースです。

• インラインデータベース。 インラインデータベースはページ内にあるため、アドレスバーにはそのページのIDが表示されます。まずデータベースをフルページとして開いてから、リンクをコピーしてください。
• リンクドビュー。 データベースのビューメニューにソースデータベースを開くがある場合、表示されているのはリンクドビューです。APIではリンクドデータベースを読み取れません。ソースデータベースを開いてそのIDを使い、ソースデータベースをコネクションと共有してください。

データベース内では、数式プロパティに id() を設定すると、各行のページIDがハイフンなしで表示されます。また、id(prop("Project").first()) で関連ページのIDを取得できます。自動化ツールで行のIDを求められたときに役立ちます。

リンクには含まれていないデータソースID

APIバージョン2025-09-03以降、データベースは1つ以上のデータソースを格納するコンテナになりました。プロパティと行はデータソースに保持されるため、データベース内の行のクエリやページの作成には、/v1/data_sources/配下のエンドポイントを使います。これらのエンドポイントに指定するのは、リンクに含まれるデータベースIDではなく、データソースIDです。データソースIDを取得する方法は3つあります。

• 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 で行に対してクエリを実行します。現在、ほとんどのデータベースにはデータソースが1つしかありませんが、それを前提に実装しないでください。Notionのアップグレードガイドでは、誰かがデータベースに2つ目のデータソースを追加すると、古いAPIバージョンを使い続けている接続では、そのデータベースが検索で見つからなくなり、そのデータベースに対する読み取り、書き込み、クエリも失敗するようになると警告しています。

コード内で

公式のJavaScript SDKを使えば、この解析処理を任せられます。2025年9月に追加されたextractPageId、extractDatabaseId、extractBlockIdは、ハイフン付きの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が含まれます。使い始めた日に起こる問題は、ほぼすべて次の6つに当てはまります。

エラーには見えない問題が、ほかにも3つあります。

• リレーションプロパティが空で返されます。 関連するデータベースも、その接続と共有してください。共有されていない場合、そのリレーションに基づくプロパティはレスポンスに含まれません。データベース間のリレーションの仕組みは、Notionのデータベース間のリレーションに関するガイドで解説しています。
• 検索しても何も見つかりません。 トークンで検索できるのは、そのトークンでアクセスできるものだけです。接続の場合は、その接続と共有されているページと、その配下のページが対象になります。
• 昨日は成功したリクエストが、今日は失敗します。 PATの有効期限が切れたか、管理者がPATを取り消したか、誰かが接続のトークンを更新した可能性があります。内部接続と公開接続では、開発者ツールのヘルスタブに、過去24時間のリクエストが、エラーコードやレート制限に達した記録とともに一覧表示されます。

2026年のNotion APIのレート制限

Notionは2026年9月9日にリクエスト制限を変更しました。以前の回答では、一律の制限として、リクエストは平均で毎秒3件、待機時間は最大15分と説明されています。現在はプランごとに上限が異なり、リクエスト数は1分単位でカウントされます。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に追加します。本番環境ではシークレットマネージャーを使います。
• Webページには絶対に埋め込まないでください。Notion APIはブラウザー上のコードからのリクエストを受け付けるため、他の人が開けるページにトークンを埋め込むと、ソースを見た誰もがそのトークンを使えてしまいます。
• チャット、サポートチケット、課題管理ツールには貼り付けないでください。AIアシスタントとの会話も例外ではありません。
• ツールごと、環境ごとに別のトークンを使います。1つを失効させても、他のツールや環境が使えなくならないようにするためです。
• 権限は必要最小限にします。外部ツールには、自分がアクセスできるすべてのページにアクセスできるPATより、共有したページだけにアクセスできる内部接続を使うほうが安全です。試験的に使うPATの有効期限は短く設定します。
• シークレットスキャンを有効にします。リポジトリとCIの両方で設定します。ntn_という接頭辞は、スキャンツールがNotionのトークンを識別できるようにするためのものです。

トークンが漏えいした場合は、次の順序で対処してください。Notionで設定 → コネクト → コネクトの開発・管理を開き、該当するコネクトまたはトークンを見つけて、内部コネクトの場合は更新をクリックし、PATの場合は失効させます。古い値を使用していたすべての箇所で、新しい値に置き換えてください。その後、ページやデータベースの最近の変更を確認し、見覚えのないコネクトがないか調べます。ワークスペース管理者は、設定 → コネクトから、どのメンバーのPATでも失効させることができます。ただし、トークン自体の表示やコピーは一切できません。

APIキーが不要な場合

• AIアプリ。 Claude、ChatGPT、Cursor、Codex、VS Codeは、OAuth経由でNotionがホストするMCPサーバーに接続するため、キーを作成する必要はありません。当サイトのNotion MCP設定ヘルパーでは、各アプリに必要な正確な設定を確認できます。例外は2つあります。BusinessとEnterpriseでは、サインイン画面を開けないクライアント向けに、ワークスペースのオーナーがMCPトークンを作成できます。また、オープンソースのセルフホスト型MCPサーバーではAPIトークンを使用しますが、Notionは現在、このサーバーの積極的なメンテナンスを行っていません。
• Notionでサインインするアプリ。 Notionの画面を開いてページの選択を求めるツールは、パブリック接続を使用しており、トークンがユーザーに表示されることはありません。
• ワークスペース内のつながりを可視化。 ページやデータベースのIDを集めて、リレーションを手作業で図にまとめることはよくあります。IVGraphはNotionのOAuth画面を通じて接続し、すべてのページ、メンション、データベース間のリレーションを、操作可能な3Dグラフとして描き出します。500ノードまで無料で利用できます。

エージェントにそのグラフを読み取らせたい場合、IVGraphのProおよびMaxプランでは、専用のサービストークンを使う読み取り専用のエージェント向けAPIを利用できます。検索、ページ内容の取得、隣接するページやページ間の経路の取得に対応しています。IVGraphのMCPサーバーはまだありません。

よくある質問