OAuth Ready
← Guide library

OAuth launch guide

Notion

Let an agent read and write pages and databases in a customer's Notion workspace

Researched draftChecked Oct 21, 2026Provider website ↗

At a glance

Moderate difficulty

Registration is self-service, but Notion's unique page-picker permission model replaces traditional OAuth scopes. The developer must handle dynamic access where users choose exactly which pages to share during authorization.

Start hereCreate a public integration at notion.so/profile/integrations.
Hands-on effort
20–40 mins
External wait
Instant for self-service; Notion Marketplace listing requires separate review
Main blocker
Notion does not use traditional string scopes — users control access via a page picker during authorization. Your app can only access explicitly shared pages.

01

Scenario this guide covers

AudienceExternal Notion users via public integration

Registration pathPublic integration created in the Notion Integrations portal

  • The agent needs to access pages and databases the user explicitly shares
  • The developer wants external users (not just their own workspace) to authorize the integration

02

Choose managed or custom

Available through ComposioEstimated

Composio lists Notion as a managed OAuth2 toolkit. Exact managed capabilities were not verified in this research pass.

Choose custom when: Use a custom public integration when you need your own app branding, specific capabilities, or full control over the authorization flow.

03

Before you start

01

A Notion account with access to the Integrations portalAlways

Developer
02

An HTTPS redirect URI for the OAuth callbackAlways

Developer
03

Users must share specific pages with the integration during authorizationAlways — the page picker is mandatory

End user

04

Permissions in plain language

(page picker)

Read and write access to user-selected pages and databasesNotion replaces traditional scopes with a page picker modal. The user selects exactly which pages and databases to share during authorization.

User-controlledSource ↗
Read user information (capability)

Access the authorizing user's name and emailOptional capability enabled in the integration settings for social login or user identification.

StandardSource ↗

05

Your setup path

1
Developer

Create a public integration

Register a public integration to get OAuth credentials.

Go to notion.so/profile/integrations, click New integration, choose Public integration, set the name, logo, redirect URIs, and installation scope.

Expected result: A Client ID and Client Secret for your public integration.Open official page ↗Official source · Notion
2
Developer

Set capabilities and installation scope

Choose whether any workspace can install or only selected workspaces.

In the integration settings, configure capabilities (e.g., read user info) and set the installation scope. Note: installation scope cannot be changed after creation.

Expected result: The integration is configured with the correct capabilities.Official source · Notion
3
Developer

Implement the OAuth flow

Direct users to Notion's authorization endpoint and exchange the code for tokens.

Redirect users to https://api.notion.com/v1/oauth/authorize with client_id, response_type=code, owner=user, and redirect_uri. Exchange the returned code at https://api.notion.com/v1/oauth/token using Basic auth (Base64 of client_id:client_secret).

Expected result: An access_token scoped to the pages the user selected in the page picker.Open official page ↗Official source · Notion
4
Developer

Test API access with selected pages

Verify the agent can read and write the user-shared pages.

Use the access token with Authorization: Bearer and Notion-Version: 2022-06-28 headers to search or retrieve pages via the Notion API.

Expected result: Successful API responses for the pages the user shared.Open official page ↗Official source · Notion

06

Review and waiting

RequirementNone for self-service distribution
Decision ownerEnd user / workspace member
Published / known waitInstant for self-service

Public integrations can be installed by any workspace without Notion review. Marketplace listing is a separate, optional submission process.

Prepare this evidence

    07

    When you get blocked

    The integration cannot see any pages or databases.+

    Likely cause: Users must explicitly select pages to share in the page picker during authorization. If no pages are selected, the integration has no access.

    Recovery: Guide users to select the relevant pages and databases during the OAuth consent step. Users can also share pages later from the Notion sharing menu.

    Official help ↗
    Installation scope cannot be changed.+

    Likely cause: Notion locks the installation scope (any workspace vs. selected workspaces) at creation time.

    Recovery: Create a new integration with the desired installation scope.

    Official help ↗

    08

    Who does what

    Agent

    Can prepare

    • Map agent actions to Notion API endpoints
    • Construct the OAuth authorize URL
    • Draft API calls for page and database operations
    You

    Must complete

    • Create and configure the public integration
    • Secure client credentials
    • Implement token exchange
    • Guide users to share relevant pages
    Provider

    Decides

    • Each user decides which pages to share via the page picker
    • Notion reviews Marketplace listings separately

    09

    Sources and limits

    01

    Notion Authorization guideNotion · checked 2026-10-21

    ↗    02

    Notion API ReferenceNotion · checked 2026-10-21

    ↗
    What we did not verify
    • No Notion integration was created or tested by this project.
    • The page-picker model means traditional scope comparisons do not directly apply.
    • Marketplace listing was not investigated.