Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cloudflare/cloudflare-os/llms.txt

Use this file to discover all available pages before exploring further.

The Notion Gatekeeper connects Cloudflare OS to Notion workspaces via OAuth 2.0 public integration, giving agents and Gadgets the ability to read and write pages, query and create database entries, manage comments, and search across your workspace. Page bodies are exchanged as Markdown for easy agent consumption, and database property values use a simplified union type that agents can work with without needing to understand Notion’s raw API schema.

​
Resource Types

Access is granted at one of two granularities. You can give an agent access to a specific page or database, or grant workspace-level access for broader discovery and search.
Notion’s page-picker during the OAuth flow controls which pages and databases are actually reachable, regardless of the grant granularity. Even a workspace-level grant can only reach pages the user explicitly shared with the integration during authorization.
GranularityResource URLSession type
Page — read/write a single page and its childrenhttps://www.notion.so/:path+ (detected as page server-side)NotionPage
Database — read schema, query rows, create entrieshttps://www.notion.so/:path+ (detected as database server-side)NotionDatabase
Workspace — search, open any shared page or databasehttps://* (catch-all)NotionWorkspace
The session type (NotionPage vs NotionDatabase) is resolved server-side from the Notion API response — pasting any notion.so URL will route to the correct session type automatically.
Page/Database grants are narrow: the Gadget can only reach the specific resource you introduced it to. Workspace grants are broader: the agent can discover and search across all pages and databases the integration was given access to during the OAuth flow. Use workspace grants when you want the agent to be able to find relevant content on its own; use page/database grants when you want to restrict access to a specific resource.

​
Setting Up Notion OAuth

1

Create a Notion public integration

  1. Go to notion.so/my-integrations and click New integration.
  2. Give it a name (e.g., “My Company OS”) and select the associated workspace.
  3. Under Integration type, choose Public (not Internal).
  4. Click Submit.
2

Configure capabilities

In the integration settings, under Capabilities, enable:
  • Read content — required for all read operations
  • Update content — required for write operations (page edits, database row creation)
  • Insert content — required for creating new pages and sub-pages
  • Read comments — required to read page comments
  • Insert comments — required to post new comments
  • Read user information without email — used for displaying connected user identity
Click Save changes.
3

Set the OAuth redirect URI

In the integration settings, go to OAuth Domain & URIs and set the Redirect URIs:
  • Local dev: http://localhost:8787/gatekeeper/notion/oauth
  • Production: ${PUBLIC_BASE_URL}/gatekeeper/notion/oauth
Click Save.
4

Copy your credentials

Go to Secrets in the integration settings and copy the OAuth client ID and OAuth client secret.
5

Configure credentials

For local development, set these in the repo-root .dev.vars:
.dev.vars
NOTION_CLIENT_ID=your-client-id
NOTION_CLIENT_SECRET=your-client-secret
The dev server maps NOTION_CLIENT_ID / NOTION_CLIENT_SECRET into the Worker’s CLIENT_ID / CLIENT_SECRET automatically.
6

Verify the setup

  1. Start the application in dev mode (pnpm dev-server + pnpm dev-client).
  2. Create or open a Gadget and navigate to the Connections tab.
  3. Click + New Connection and choose Notion.
  4. Connect your Notion account — you will be redirected to Notion’s authorization page.
  5. In Notion’s page picker, select the pages and databases you want to share with the integration.
  6. After authorizing, the tab closes and you are back in the Gadget.
  7. Paste a Notion page or database URL to introduce the specific resource, or choose a workspace-level grant.

​
What Agents Can Do

  • search — full-text search across all shared pages and databases
  • getPage — fetch a specific page by URL or ID
  • getDatabase — fetch a specific database
  • createPage — create a new top-level page (queued for approval)
  • listUsers — list workspace members

​
Approvals and Simulation

Every read operation is recorded as an observation. Every write — creating a page, appending content, posting a comment, archiving — is staged in the approval queue and not sent to Notion until you approve it. While writes are pending approval, the agent sees simulated results: provisional IDs for created pages, body overlays for edited content. Page, database, and user responses are cached with short TTLs for performance.

​
Data Sources

Notion’s newer API model splits a database into one or more data sources. Database query, getSchema, and row creation resolve the database’s primary data source automatically. Pages, blocks, comments, and search use the standard Notion API version to keep user-facing IDs and URLs consistent. This detail is fully abstracted from the agent’s Session API.

​
Observer Tracking

When a Gadget that uses Notion resources is shared with a collaborator:
  • Page and Database grants — the collaborator must connect their own Notion account and verify that the specific page or database was shared with their integration during their own OAuth flow
  • Workspace grants — the collaborator must connect their own Notion account; the gatekeeper tracks which pages and databases were accessed and verifies the collaborator’s access to each one
This ensures collaborators cannot read Notion content they were not explicitly given access to, even through a shared Gadget.

Build docs developers (and LLMs) love

Get started for freeTalk to us