OAuth PathFor AI Agents
Back to Guides
AI generated, checked against Notion docs on 2026-10-31: Provider OAuth rules and review policies change frequently. Always verify current submission requirements with the official Notion documentation before submitting for production approval.

Internal integrations take minutes; public OAuth requires zero manual Notion review before going live.

developers.notion.comAI generated, checked against Notion docs on 2026-10-31
At a glance
Executive breakdown in plain language
Difficulty
EASY

Internal integrations take minutes; public OAuth requires zero manual Notion review before going live.

Setup Time
10 - 15 minutes

Active engineering effort required to register the OAuth app, set redirect URLs, and obtain credentials.

Approval Wait
Instant (no mandatory review required)From official docs

Notion allows public distribution as soon as company information and valid URLs are provided.

Biggest Blocker
Agent receives 404 or empty results when querying pages or databases

Fix: Notion uses granular page-level permissions. The user must explicitly grant the integration access to pages using the 'Add connections' menu inside Notion page settings.

Required Before Starting
From official docs
• Notion user account and workspace (From official docs)
• Public HTTPS redirect URI (From official docs)
• Published Privacy Policy and Terms of Service URLs (for public OAuth) (From official docs)
• Integration icon (PNG/JPEG format, square recommended) (From official docs)

Step-by-Step Setup Guide

4 steps
From official docs

Follow these sequential actions to register your OAuth application and configure endpoints.

1

Create an Integration in Notion Developers

Go to notion.so/profile/integrations and click 'New integration'. Assign an app name and choose an associated workspace.

Open in Notion Console
2

Select Integration Type & Capabilities

Choose 'Internal integration' for your own workspace, or toggle to 'Public integration' to allow any Notion user to connect. Select capabilities (Read, Update, Insert content).

Open in Notion Console
3

Configure OAuth Redirect URI and Company Info

In the 'Distribution' tab, input your HTTPS redirect URI, your company name, and links to your privacy policy and terms.

Open in Notion Console
4

Retrieve OAuth Credentials

Copy your OAuth Client ID and Client Secret from the 'Secrets' tab. Store them in `.env.local`.

Open in Notion Console

Common Blockers & Fixes

2 blockers
From official docs

Anticipate the pitfalls and approval rejections that catch most agent developers off guard.

Agent receives 404 or empty results when querying pages or databases
Action Plan: Notion uses granular page-level permissions. The user must explicitly grant the integration access to pages using the 'Add connections' menu inside Notion page settings.
Public distribution toggle fails validation
Action Plan: Notion verifies that privacy policy and terms URLs are reachable HTTPS links. Ensure both endpoints return HTTP 200.

What an agent can do vs what you must do

Agent vs Developer
From official docs

A clear division of labor: tasks your autonomous agent can handle vs actions requiring human developer authorization.

What an Agent Can Do
  • Construct the Notion authorization URL with proper `client_id`, `redirect_uri`, and `response_type=code`
  • Handle the OAuth callback and exchange authorization code with `https://api.notion.com/v1/oauth/token`
  • Parse and securely persist workspace ID, bot ID, and access tokens
What You Must Do Yourself
  • Create the integration in the Notion Developer portal
  • Upload your application logo and brand details
  • Publish valid Privacy Policy and Terms of Service web pages

Managed OAuth vs Custom Credentials

From official docs

Evaluate whether using a managed integration platform (like Composio) is sufficient or if you must create your own app.

This tool was built for a Composio assignment, and Composio sells managed OAuth.
When Managed OAuth is Enough
Composio's managed Notion integration is ideal for 95% of use cases because Notion users always select which pages to share during the consent screen, regardless of whether the app is managed or custom. This tool was built for a Composio assignment, and Composio sells managed OAuth.
When Custom Credentials are Required
A custom Notion integration is only required if you want your company's custom logo and brand name shown at the top of the Notion workspace connection selector.

Key Claims & Verification Status

From official docs

Specific factual statements evaluated against sources.

Notion does not require manual review or approval before public OAuth can be used in production.
Users must explicitly grant page-level permissions to the integration during or after OAuth authorization.

Official Sources & Documentation

2 sources
From official docs
Notion API: Create an IntegrationNotion API: Authorization Guide

Open Questions & Uncertainties

1 open questions
Unverified estimate

Areas currently subject to policy changes or requiring ongoing real-world verification.

  • Will Notion introduce an app review process for integrations requesting workspace-wide search permissions in the future?