Notion AI agent: scoped access with an approval gate
A how-to for handing an AI agent scoped access to Notion: the six named tools the connector really exposes, which writes need approval, and how to connect safely.
Last updated
7 minute read · Written by the team that builds UtilitySpaces. More about UtilitySpaces.
In UtilitySpaces, a Notion AI agent is an external agent that acts on your behalf against Notion — reading pages and databases, and writing to them — through the Notion connector. It is not Notion AI. It is an agent in a shared inbox or on a schedule that you have given scoped access to Notion, and it calls the connector’s tools by name with exact matching.
That access is narrow by construction. You create an integration token in Notion and paste it once; it is encrypted, bound to your workspace and never shown again, and the connector only ever reaches the pages and databases a workspace admin explicitly shares with it. Reads run on their own — Search, Query database and Get page — but the two write tools, Create page and Append blocks, always stop at a human approval gate unless an admin has switched the connection to run writes without asking. Every call, approved or not, is written to a hash-chained audit trail, and run cost is metered per session so nothing runs unseen. Give it the box it needs and nothing more.
What is a Notion AI agent in UtilitySpaces?
A Notion AI agent in UtilitySpaces is a role you attach to an AI agent — defined in the shared inbox or on a schedule — that calls the Notion connector’s tools directly against your Notion workspace. The connector is per-app and scoped: it gets its own integration token, and it exposes exactly six named tools, listed on the Notion connector, so the agent cannot invent a URL or guess a database it was not handed. Matching is exact: a misspelled tool name is a no-op, not a wild write.
Reads run without asking. Search finds pages and databases shared with the integration, Query database returns rows with optional filter and sorts, and Get page returns a page’s properties by id. There is one cheap read that is not about your data at all: Get bot user returns the integration’s own bot user — a token check rather than a page fetch.
The two writes are where the gate earns its name. Create page makes a page under a parent page or database (a POST), and Append blocks adds content blocks to a page or block (a PATCH). Both land in Approvals unless a workspace admin has set this connection to run writes without asking. The gate exists because a wrong write is not a clean retry: it edits a real page that someone else will read.
Which six tools does the Notion connector expose?
UtilitySpaces never lists a tool that does not exist — the table that follows is generated from the connector catalogue the product runs on, so it is exactly what an agent can call.
| Tool | What it does | Waits for approval by default |
|---|---|---|
| Get bot user | Get the integration’s own bot user (cheap token check). | No — read only |
| Search | Search pages and databases shared with the integration. | No — read only |
| Query database | Query rows of a database with optional filter and sorts. | No — read only |
| Get page | Get a page’s properties by id. | No — read only |
| Create page | Create a page under a parent page or database. | Yes — it writes |
| Append blocks | Append content blocks to a page or block. | Yes — it writes |
Four read tools, two write tools. Get bot user is the safe one to lead with in testing: it proves the token works without touching a single page.
How does a scoped Notion connection contain the blast radius?
Notion does not use OAuth for this connection; it uses an integration token you generate in Notion and paste once into the Notion connector. That token is encrypted at rest and bound to your workspace, and it is never read back or displayed again. A leak of the connector store therefore cannot hand over a plaintext Notion credential.
The meaningful scope is Notion’s own. The integration only ever sees the pages and databases that a workspace admin explicitly shares with it in Notion’s UI — nothing else in the workspace is reachable, by any tool. That is the containment boundary: scope it to the one database an agent needs and the rest of the workspace stays out of reach.
Credential isolation is per connector, not per workspace as a whole. Each app connector gets its own bound credential, so a mistake inside the Notion connection cannot ride across tenants or into another app. Each outbound call also passes one guarded fetch — the connector security posture sets out exactly how.
Revocation is a switch in Notion, not a question for UtilitySpaces. Revoke the token and the connection fails safe on the next call; there is no stored credential to rotate here.
Why does every Notion write stop at a human approval gate?
Reads run on their own because reading is cheap and reversible. Writes do not. Create page and Append blocks mutate documents that real people read and edit, and the cost of a wrong one is not a clean retry — it is a page created in the wrong place, or content blocks appended to the wrong page.
So every write goes to Approvals. An owner or admin approves or rejects it, and the decision — approved, rejected, or unattended — is written to a hash-chained audit trail. That is the approval gate’s shape across every connector, and the Notion-specific detail is which two tools it holds: the same approval gate design that applies to every app.
A workspace admin can mark this Notion connection to run writes without asking, but only deliberately and only after the gate has proven itself on the read-only path first. The default, and the safe one, is ask every time.
How to connect an AI agent to Notion safely?
- In Notion, create an internal integration and copy its internal integration token (the API key).
- In UtilitySpaces, add the Notion connector and paste the token once. It is encrypted and bound to your workspace and never shown again.
- In Notion, share only the pages and databases the agent needs — read access for the ones it should search and query, and at most the specific parent page or database it may write to.
- Leave the connection on Ask a person first, so Create page and Append blocks land in Approvals instead of firing.
- Run a read-only test before any write: Search a shared database, then Get page on its result. Only once that works should a write wait for approval.
What cost controls and audit trail apply to Notion agents?
Cost is metered per session, not per tool. The agent’s reads and the model turns behind them show up per run, by workspace, on the cost breakdown; a weekly glance at spend per agent catches the one that doubled. You can bring your own model-provider key to move the model bill onto a statement you already read. There is no automatic shut-off — the ceiling is a habit of reading that page plus revocation.
Every write attempt is logged, including Append blocks, Create page, approved, rejected or abandoned. Each entry lands in the audit trail and names who approved what and when; the audit trail page covers the platform around it. Reads are not individually logged as actions, but the run thread records which reads the agent called, so a review can see what informed a write.
Append blocks adds content to the end of whatever page or block it is pointed at, and the connector cannot remove blocks. Confirm the target page id on every write before you let a Notion connection run writes without asking.
Limits, trade-offs, and when not to use a Notion AI agent
A few limits are worth naming up front. The integration token sees only what you share with it; share the wrong database and the agent can read it. Scope in Notion is page and database sharing, not row-level — Query database returns all rows a shared database exposes, so narrow the sharing before you narrow the role text.
Append blocks can only add to the end of a page or block; the connector cannot remove blocks, so let a write run unattended only after you have confirmed the target page id in every call. That is the trade-off that buys the safety.
The connector is generated from the catalogue, so it exposes exactly the six tools above and no Notion feature the API supports but the connector does not map — relation and rollup fields, for example. If your workflow depends on those, this agent will not do it.
Cost is metered, not capped. The ceiling is reading the cost page and revoking a token, not a hard stop the product pulls. If you need the agent to see pages across the whole workspace, you are in the wrong place: share explicitly instead — that is the trade-off that keeps the blast radius small.
We build UtilitySpaces.