はじめに

hkob の雑記録の第505回目(連続78日目)は、一昨日の続きで Developer Docs のChangeLog を紹介します。今日は Developer portal and personal access tokens です。

5/12 の ChangeLog

5/12 に以下の ChangeLog が出ていました。

新しい Developer portal が公開された。Notion の開発者向けツール（connections、Workers、personal access tokens）を管理するための単一の場所として提供される。

最初に Developer portal を紹介しています。これまでインテグレーションキーを管理するページでしたが、開発者向けのポータルサイトとなりました。あとでページ紹介します。

Personal access tokens（PAT）は、スクリプト、CLI ワークフロー、Workers、信頼できるツールが「1 人の Notion ユーザーの権限」で動作するための、ユーザースコープのトークンである。PAT には Notion API アクセス、Workers アクセス、またはその両方を付与できる。

ワークスペース管理者は、ワークスペース内で作成された PAT を閲覧・失効（revoke）できるようになった。対象プランでは、Notion API アクセス付き PAT を「誰が作成できるか」も設定できる。デフォルトはプランにより異なる: Free はワークスペースオーナーのみ、Plus は全メンバー、Business はワークスペースオーナーのみ、Enterprise はワークスペースオーナーと選択したグループ。

もう一つは Personal access tokens (PAT) という新しいトークンが用意されました。これまでの internal integration は指定したページにだけにアクセスできるbotユーザのためのトークンでした。この場合、自分のコメントを編集したりすることは不可能でした。

Developer portal

Developer portal のトップ画面はこんな感じになります。ポータルのトップはこのような形になっています。今は、Notion CLI のインストールと新しいワーカーの設定が最初に用意されています。

次のタブはコネクトです。ここは今までの my-integration に相当するものですね。

次のタブはワーカーです。先日作成した moodle-webhook が存在しています。

最後のタブは個人用アクセストークンです。私のところにも Notion CLI という名前のトークンが登録されています。こちらは ntn login で作成されたものです。

Personal Access Token

ここでは以下のページの内容を翻訳しながら解説します。

Personal access tokens（PATs）はユーザースコープの bearer トークンである。PAT は 1 つのワークスペース内の 1 人の Notion ユーザーに紐づき、Notion API を呼び出す際にそのユーザーのワークスペース所属とページ権限を用いる。PAT は、internal connection を作成したり、public connection の OAuth フローを実装したりせずに「自分として」認証したい場合に有用である。

上にも書いたようにコメントなどは internal integration ではアクセスできないので、自分として認証したいことが多くなります。特に最近はデータベースでもページレベルのアクセス権限を設定できるようになり、ユーザとしてアクセスできるのかは重要になっています。

PAT を使う場面

1 人の Notion ユーザーを適切なセキュリティ境界として扱える、個人用途または開発者オーナーのワークフローで PAT を使う:

自分のワークスペース内の作業を自動化するローカルスクリプト、ノートブック、コマンドラインツール。

共有 connection を作る前の、Notion API に対する開発・テスト。

Notion トークンの貼り付けを求め、あなたの Notion 権限で動作すべきサードパーティツール。

Notion CLI を用いた Notion Workers の開発・デプロイ。

多数の Notion ユーザーが利用するプロダクトの認証モデルとして PAT は使わない。その場合は public connection を作成し、各ユーザーが OAuth によりアクセスを許可できるようにする。チーム所有の自動化で、ワークスペースレベルの安定した bot が必要なら internal connection を使う。

ここでは PAT を使うべき用途が示されています。一方で、チームで取り扱う認証の場合には、public integration や internal integration を使うように書かれています。これらは積極的にコネクトで接続したページにしかアクセスできないので、意図しないページへのアクセスをされることがないという安心感もあります。

PAT の仕組み

PAT は Developer portal で作成する。作成時に以下を選ぶ:

トークン名

トークンが属するワークスペース

トークンの capabilities

PAT には 2 種類の capability バンドルがある:

Capability 許可されること

Notion API Notion の REST API を通じて、コンテンツの read / create / update / search、コメントの read / create、対応しているユーザー情報の read。

Workers Notion CLI による Notion Workers のデプロイと管理。

Notion API の capability は、ワークスペースの「PAT 作成ポリシー」により制御される。Workers capability はワークスペースメンバーに付与できるが、Workers 機能の利用可否は Workers 利用時に別途チェックされる。PAT によるリクエスト認証は、他の Notion API トークンと同様:

HTTP
GET /v1/users/me HTTP/1.1
Authorization: Bearer {PERSONAL_ACCESS_TOKEN}
Notion-Version: 2026-03-11

Capability	許可されること
Notion API	Notion の REST API を通じて、コンテンツの read / create / update / search、コメントの read / create、対応しているユーザー情報の read。
Workers	Notion CLI による Notion Workers のデプロイと管理。

Notion API で利用する場合には、基本的にユーザができることが全て許可されているようです。internal integration のように読み込みのみのような制限をつけることはないようです(そもそも設定する場所がありません)。また、PAT は Workers でも利用されるので、 ntn login すると自動的に PAT が生成されます。

権限とコンテンツアクセス

PAT は、それを作成したユーザーとして振る舞う:

作成者がアクセスできるページ、データソース、データベース、コメント、ファイル等にアクセスできる。

Add connections による bot 共有は不要。

作成者がページへのアクセス権を失う、またはワークスペースから離脱すると、PAT もそのアクセス権を失う。

"me" フィルタやワークスペースレベルのプライベートページ作成など、「認証ユーザー」に依存する API 挙動は PAT の作成者が基準になる。

PAT は internal connection と意図的に異なる。internal connection は独立した bot ユーザーとして動作し、その connection に明示的に共有されたページにのみアクセスする。一方、PAT は実ユーザーの権限を使うため、チーム所有の自動化よりも「ユーザー所有」のワークフローに向く。

List all users は PAT では利用できない。PAT は Retrieve token’s bot user で認可ユーザーを取得でき、Retrieve a user でも同じユーザーを取得できる。

上にも書いたように PAT は個人に関連するページに対する権限を有しています。

ワークスペース管理者による制御

ワークスペース管理者は Settings & members → Connections から PAT を管理できる:

ワークスペース内で作成された PAT（有効/失効）を一覧表示

トークン名、作成者、status で検索・フィルタ

トークン作成者、（失効済みの場合）誰が失効させたかを確認

有効な PAT を失効

Notion API アクセス付き PAT の作成者を制御

管理者は他メンバーのトークン secret を表示/コピーできない。表示/コピーできるのはトークン作成者本人のみ。

管理者がポリシー変更により、あるメンバーの「Notion API アクセス付き PAT の作成」を禁止すると、そのメンバーの既存 PAT は Notion API リクエストに対して動かなくなる。リクエストはポリシーが再度許可するか、別の有効なトークンを使うまで、次の unauthorized エラーを返す。

ワークスペース管理者は、メンバーのトークンを検索したり失効したりすることができます。ただし、トークンの中身は表示することはできません(これができたら問題ですからね)。なお、既存の PAT が失効された場合には、 unautorized となるようです。

PAT を作成できる人

Guests and restricted members は PAT を作成できず、Notion CLI（ntn login）でもログインできない。トークン作成はフルメンバーのみが可能で、以下の「PAT 作成ポリシー」に従う。ワークスペースオーナーは常に Notion API アクセス付き PAT を作成できる。

Plan デフォルトの PAT 作成ポリシー管理者による制御

Free Workspace owners のみ。設定不可。

Plus 全 workspace members。設定不可。

Business Workspace owners のみ。 Admins が Workspace owners のみ または 全 workspace members を選択できる。

Enterprise Workspace owners と選択したグループ。 Admins が Workspace owners のみ / Workspace owners と選択したグループ / 全 workspace members を選択できる。

Enterprise では「選択したグループ」は PAT creators の設定ページから管理される。グループが未選択の場合、Notion API アクセス付き PAT を作成できるのはワークスペースオーナーのみ。

Plan	デフォルトの PAT 作成ポリシー	管理者による制御
Free	Workspace owners のみ。	設定不可。
Plus	全 workspace members。	設定不可。
Business	Workspace owners のみ。	Admins が Workspace owners のみまたは全 workspace members を選択できる。
Enterprise	Workspace owners と選択したグループ。	Admins が Workspace owners のみ / Workspace owners と選択したグループ / 全 workspace members を選択できる。

PAT を作成できる人は上記の表のようになっています。Plus は全メンバーが設定できてしまい、制限することはできません。Business はデフォルトでワークスペースオーナーのみとなっていますが、設定で全メンバーに許可することもできます。エンタープライズはグループを設定して、そのグループの人だけ許可ということもできるようです。

PAT を作成する

Developer portal を開く。

Personal access tokens に移動する。

New personal access token をクリックする。

名前、ワークスペース、付与する capabilities を選ぶ。

Create token をクリックし、トークン値をコピーして安全に保管する。

PAT は作成から 1 年後に失効する。期限切れ前に新しい PAT を作成し、スクリプトやツール側のトークンを更新する。

上記の Developer portal の PAT の場所で新規に作成することができますが、worker を作成する人であれば、 ntn login で作成した方が早いと思います。1年で有効期限が切れてしまうので、その前にトークンの切り替えをする必要があります。直前にリマインダーが届くかもしれませんが、念のため Notion のリマインダなどを設定しておくといいのではないかと思います。

PAT を失効（revoke）する

PAT が露出した、不要になった、信頼できないツールと紐づいている場合は直ちに失効する。

トークン作成者は Developer portal から自分の PAT を失効できる。

ワークスペース管理者は Settings & members → Connections → All personal access tokens から、ワークスペース内の任意の PAT を失効できる。

失効後、トークンは直ちにスクリプト/ツール/Workers/それを使う API リクエストで動作しなくなる。

PAT はそのユーザの全権限を持つので、露出した場合にはかなり問題となります。この場合には、 Developer portal で失効処理をする必要があります。

セキュリティ・ベストプラクティス

PAT はパスワード同様に扱う:

PAT は環境変数または secret manager に保存する。

PAT をソース管理にコミットしない。

スクリプト/ツール/環境ごとに別 PAT を使い、1 つを失効しても無関係なワークフローを壊さないようにする。

必要な capabilities のみに絞る。

使わないトークンは失効する。

追加のガイダンスは以下を参照:

Best practices for handling API keys

ツールごとに PAT を変更しておくのはいい手だと思います。全てに同じ PAT を使ってしまうと有効期限切れでやらなければならない作業がまとめてやってきてしまうからです。新しいアプリごとに PAT を生成することで、更新時のタイムロスを軽減できます。