Connect Notion
An account of Notion is connected once, on the instance, by a person who then gives missions access to its resources; the agent never receives the credential. Read and edit the pages, page content, databases and comments of the Notion pages shared with an internal connection.
One account is one internal connection of a Notion workspace, connected with its token. One resource is one top-level page or database shared with that connection, with everything under it. Notion has no environments: moving a page to the trash and deleting a block ask first in the presets. Writes are sent silently, so Notion notifies nobody.
Permissions, presets and tools of this service: Notion plugin.
How to connect
On the instance: Accounts → Connect an account, then pick the service. A company app, when the service needs one, is registered once by an administrator under Settings → Administration → Company apps, or set in the configuration (providers.<id>.*, see configuration keys). Every instance registers its own app: this gateway never uses an app shared with another one.
The usual way: with a internal connection token pasted by hand
- Open Notion's Developer portal, go to Build, Internal connections and create a connection in the workspace you want to connect (you must be a Workspace Owner).
- On the Configuration tab, tick the capabilities listed below and choose No user information.
- Copy the token from the Configuration tab and paste it here.
- Give the connection access only to the pages and databases the agents need: on each top-level page, open the ••• menu, Connections, Add connection, or use the Content access tab. Sharing a page includes everything under it.
Where: https://app.notion.com/developers/connections
Permissions to grant at the service, and no more:
- Read content: read
- Insert content: read-write
- Update content: read-write
- Read comments: read
- Insert comments: read-write
What the connect page asks:
- Internal connection token (secret): Create an internal connection with only the capabilities the agents need, and share with it only the top-level pages and databases they may work in: everything under a shared page is reachable with this token, whatever the gateway allows.
The service's documentation: https://developers.notion.com/guides/get-started/internal-connections
Disconnecting
In Notion's Developer portal, open the connection and refresh its token on the Configuration tab, or remove the connection from the shared pages (••• menu, Connections).
Registration notes from the plugin
From the plugin's README, written for the people who register the app or create the token.
Credential and resources
Kind api-key, an internal connection token:
| Field | Pattern | Purpose |
|---|---|---|
api_token | ^\S{20,512}$ | The token of an internal connection (ntn_…; older secret_… tokens work). Not a format check: Notion advises against one. |
A Workspace Owner creates the connection at
https://app.notion.com/developers/connections (Build → Internal
connections), ticks the capabilities the agents need (Read content, Insert
content, Update content, Read comments, Insert comments) and shares the
top-level pages and databases with it. verify calls GET /v1/users/me
and refuses a token whose bot is not owned by the workspace: a personal
access token acts as its creator over everything that person can open,
which is not the resource model.
discoverResources pages through POST /v1/search for pages, then for data
sources (100 per page, at most 20 pages per kind), and returns one
resource per top-level object: one whose parent is the workspace, or whose
parent the token can neither find nor read (a GET answering 404). At most
200 roots. Discovery fails rather than truncate when a ceiling is reached.
{ provider: 'notion', ref: '1f2e…-…', displayName: 'Handbook', metadata: { kind: 'page' } }