Skip to main content

​
Overview

OneCLI connects AI agents to Notion through Notion’s OAuth flow. Agents can search your workspace, read page content, create and update pages, and query databases. The gateway injects OAuth credentials into requests to the Notion API automatically. This is useful for agents that need to look up internal documentation, create tasks or notes, or sync data with Notion databases.

​
What you will set up

  • A Notion connection through OAuth, limited to the pages and databases you select
  • Automatic token injection on Notion API requests
  • Per-agent, per-tool access to your workspace

​
Setup

1

Go to Connections

Open the OneCLI dashboard and navigate to Connections > Notion.
2

Authorize

Click Connect Notion. You’ll be redirected to Notion to authorize OneCLI. Select which pages and databases the integration can access, then click Allow access.
OneCLI connect window for Notion on Cloud, showing the Connect to Notion button.

The Notion connect window on OneCLI Cloud.

​
Self-hosted: use your own Notion integration

Skip this section on OneCLI Cloud. It’s only for self-hosted OneCLI without NOTION_CLIENT_ID and NOTION_CLIENT_SECRET set, or if you want your own company name on Notion’s consent screen.

1. Create the Notion integration

Go to notion.so/profile/integrations and select New integration. Name it OneCLI, pick your workspace, set Type to Public, and save.
Open Capabilities and turn on the ones your agents need:
In OneCLI, open Connections > Notion > Custom credentials and copy the Redirect URI. In Notion, open Configuration > OAuth Domain & URIs, paste it into Redirect URIs, and save.
OneCLI Custom credentials card for Notion with the setup guide link, the Redirect URI and its copy button, and the client ID and secret fields.

Copy the Redirect URI from Custom credentials in OneCLI.

Notion integration settings, OAuth domains and URIs section, with https://onecli.example.com/v1/apps/notion/callback in Redirect URIs.

Notion's OAuth domains & URIs section with the OneCLI Redirect URI.

In Notion, open Configuration and copy the OAuth Client ID and OAuth Client Secret. Paste both into Connections > Notion > Custom credentials, select Save & Connect, and allow access in Notion.
Notion integration named OneCLI, Configuration tab showing the OAuth Client ID, a hidden OAuth Client Secret, and the Authorization URL.

Your integration's Configuration tab in Notion: the OAuth Client ID and Client Secret.

​
What agents can do

  • Search across all accessible pages and databases by keyword
  • Read the full content of a page (text, headings, lists, tables, callouts)
  • Create new pages in a specified parent page or database
  • Update existing page content (append blocks, modify properties)
  • Query databases with filters and sorts (e.g., all tasks with status “In Progress”)
  • Create new entries in a database with specified property values
  • Update database entry properties (status, assignee, dates, tags)
  • Read database schema (property names, types, select options)
  • Archive and restore pages
  • Read and add comments on a page

​
Controlling access

Access is per agent: grant the connection to each agent that needs it, choosing per tool what runs freely, what needs human approval, and what stays blocked — a read-only agent is a single grant. Organization rules add guardrails on top, like rate limits and blanket blocks. Everything is checked before credential injection, so a blocked request never reaches Notion.

​
FAQ

Only the pages and databases you select when you authorize OneCLI in Notion.
No. The token stays in OneCLI, and the gateway adds it at the proxy. See How it works.
Yes. A read-only agent is a single grant.