verapli
Sign inJoin free
Menu

Guides · productivity · Popular APIs

Notion API connection (integration)

Create an internal connection (static token for one workspace), a personal access token, or a public OAuth connection in the Notion Developer portal; Marketplace listing needs a Notion security review.

Researched · not yet run liveLast researched 25 October 2026 · Notion · provider site

Researched, not yet run live. Built from the provider’s official pages (linked below). A person hasn’t walked this flow end to end yet, so check each step against the source.
Do this with verapliJSON for agents

Who owns what

Connections belong to a Notion workspace (development workspace for public connections).

  • Notion workspace organisationOlder docs say only Workspace Owners create connections; the May 2026 release says any member can [to verify per workspace settings].

Steps

Steps marked “human step” are ones only you can do: verapli never signs in, submits, pays or accepts terms for you.

  1. Create an internal connection (single workspace)

    In the Developer portal choose Build > Internal connections > Create a new connection, name it and pick the workspace, set capabilities.

    • verapli co-pilot
    • Human step: You press submit

    Where: https://app.notion.com/developers

  2. Copy the internal API token

    Open the Configuration tab and copy the API token; keep it in an environment variable.

    • verapli co-pilot
    • After: Create an internal connection (single workspace)

    verapli captures NOTION_API_TOKEN here by plain code: encrypted in your browser, never shown to AI.

    Where: https://app.notion.com/developers

  3. Share pages with the connection

    In each page's ••• menu choose Connections / Add connections and pick yours (or use the Content access tab); unshared pages return errors.

    • Guided by hand
    • Human step: You press submit
    • After: Create an internal connection (single workspace)
    If something goes wrong (1)
    • API returns an object-not-found style error for a page you can see: Share that page (or a parent) with the connection. [1]

  4. Create a public OAuth connection (other workspaces)optional

    Build > Public connections > Create new connection; enter name, development workspace, redirect URIs, capabilities, and installation scope (Any workspace is required for Marketplace and cannot be changed later).

    • verapli co-pilot
    • Human step: You press submit

    verapli captures NOTION_OAUTH_CLIENT_SECRET here by plain code: encrypted in your browser, never shown to AI.

    Where: https://app.notion.com/developers

  5. List on the Notion Marketplace (optional)optional

    Fill in listing details in the Listings section and submit; public connections must pass a Notion security review before listing.

    • Guided by hand
    • Human step: The provider reviews it
    • After: Create a public OAuth connection (other workspaces)

    Where: https://app.notion.com/developers

Terms and gotchas

Plain-English summary, not legal advice. Each card links its source.

Can cost moneyThe rules say

Installation scope is fixed at creation; "Selected workspaces only" connections can never be listed on the Marketplace. [3]

What you end up with

Env varSecretFormatWhat it is
NOTION_API_TOKENsecretopaque token stringInternal connection API token (or a personal access token)
NOTION_OAUTH_CLIENT_IDnot secretopaque id stringPublic connection OAuth client ID
NOTION_OAUTH_CLIENT_SECRETsecretopaque secret stringPublic connection OAuth client secret

Pricing

  • Rate limits depend on plan (600/min per connection on Business and Enterprise, 180/min otherwise); no separate API fee found [to verify].

Source [6]

For agents

The same entry as JSON: /api/v1/entries/notion/integration · requirements /api/v1/requirements/notion/integration · terms /api/v1/terms/notion/integration.

Remote MCP (read-only, no auth)
claude mcp add --transport http verapli https://verapli.com/mcp

> "What do I need for Notion API connection (integration), and how long will it take?"
  → tools/call requirements { "provider_id": "notion/integration" }

Sources

  1. Authorization Internal connections use a static API token for one workspace; public connections use OAuth 2.0 with installation scope Any workspace or Selected workspaces (not changeable); PATs act as the user; pages must be shared with an internal connection or requests error; OAuth access and refresh tokens. · accessed 25 October 2026 · official
  2. Overview Public connections must pass a Notion security review before Marketplace listing; only "Any workspace" connections are Marketplace-eligible. · accessed 25 October 2026 · official
  3. Public connections Create via Developer portal > Build > Public connections; fields include name, workspace, redirect URIs, installation scope, capabilities; client ID and secret in Configuration tab. · accessed 25 October 2026 · official
  4. Internal connections Build > Internal connections > Create a new connection; API token in Configuration tab; no page access until content is shared. · accessed 25 October 2026 · official
  5. Notion release notes, May 13, 2026 app.notion.com/developers is the dedicated Developer portal; any member can build connections (not just Workspace Owners). · accessed 25 October 2026 · official
  6. Request limits 600 requests/min per connection on Business and Enterprise, 180/min on other plans; data source queries about 3 req/s. · accessed 25 October 2026 · official

Provider rules change. This page is generated from verapli registry version 2026.1025.316; spotted something out of date? Tell us. Notion is not affiliated with verapli.