← library
Self-serve (+ optional review)
Docs / knowledge·curated + hand-verified·checked 2026-10-28
difficulty
2/5

Create a public connection and OAuth works for any workspace. Marketplace listing needs a security review. The real surprise: your agent only sees pages users pick at consent.

First working connection
~20 minutes
Production / approved
Same day unlisted · Marketplace listing: review (no published SLA)
Composio managed OAuth
Available: ship today
Composio offers a managed Notion app. Bring your own to show your name in Notion's page picker and to list in the Notion Marketplace.
who does itagent 3you 3provider 0
evidencetested 3sourced 15inferred 5

01Pick your path

Personal access token / internal connection
when Scripts or an agent for your own workspace.
→ No OAuth, no review. One workspace (or one user) only.
Public connection, selected workspaces
when Pilot with named customer workspaces.
→ OAuth for each user, but only workspaces you pick at creation. Not Marketplace-eligible.
Public connection, any workspace
when Any Notion user should be able to connect.
→ OAuth for everyone. Marketplace-eligible after Notion's security review.

02Time & effort

Hands-on work
2.2 h – 4.3 h
Waiting on others
7 days – 4 weeks
You're actually working
<1% of elapsed time
Phases
3
start↑ first working connection, then production pathproduction
  1. DEVCreate public connection in the Developer portal10–20 minutessourced[notion-auth]
  2. DEVImplement OAuth + page-picker aware UX2–4 hoursinferred
  3. PRODMarketplace security review (optional)wait 1–4 weeksinferredNotion doesn't publish a timeline. This range is our estimate.
agent can do it you waiting on providerbar widths ∝ √time, so short tasks stay visible

03Steps

0/6 done

Get a working connection

  1. Decide the installation scope up frontagentsourced[notion-public]

    'Any workspace' (Marketplace-eligible) vs 'Selected workspaces only' (not eligible). You choose at creation time.

  2. Create a public connection in the Developer portalyousourced[notion-auth][notion-ov]

    Fill in connection details, redirect URI(s) under OAuth configuration, and capabilities (read/update/insert content, comments…). Note that Notion now calls integrations 'connections'.

    ↗ www.notion.so/profile/integrations
  3. Copy client ID/secret from the Configuration tabyousourced[notion-auth]

    Store them in your secret manager. Never ship them to the browser.

  4. Build the authorize URL and token exchangeagenttested[notion-auth][probe]

    Authorize: https://api.notion.com/v1/oauth/authorize with client_id, response_type=code, owner=user, redirect_uri. Exchange the code at /v1/oauth/token with HTTP Basic auth (client_id:secret).

  5. Design for the page pickeragentsourced[notion-public][notion-auth]

    Users choose which pages to grant during OAuth. Your agent sees nothing else. Offer a template, or tell users to share the right pages, or the agent will look broken.

Make it production-ready

  1. Submit for Marketplace listing (optional)yousourced[notion-public]

    Listing requires passing Notion's security review. You can run a public connection without listing it.

04Requirements, scopes & nuances

You'll need

  • ▸A Notion workspace where you can create connections (workspace owner for internal connections). sourced[notion-auth]
  • ▸Redirect URI(s) registered on the connection. sourced[notion-auth]
  • ▸Privacy policy and terms URLs are expected for public connections. inferred[n8n]

Gotchas

  • !Access is per-page, chosen by the user at consent. New pages aren't visible to your agent unless shared. sourced[notion-public]
  • !Installation scope is chosen at creation. 'Selected workspaces' connections can't be listed in the Marketplace. sourced[notion-public]
  • !Terminology changed ('integrations' → 'connections'). Many tutorials use old UI names. sourced[notion-ov]
  • !Notion's docs say the Authorization URL field populates after the public connection is 'submitted for review'. We couldn't confirm whether that means the creation form or the Marketplace review. inferred[notion-auth]
Scope / permissionTierNoteEvidence
Read contentbasicNotion uses 'capabilities', not OAuth scope strings.sourced[notion-ov]
Update / Insert contentbasicWrite capabilities.sourced[notion-ov]
Read comments / user infobasicOptional capabilities. Email access is a separate choice.inferred

05If you get blocked

✕Agent says it can't find a page the user sees in Notion.sourced[notion-public][notion-auth]

→ The page wasn't granted. Have the user re-run OAuth and select it, or share it with the connection via '…' → Connections.

✕No Marketplace timeline from Notion.sourced[notion-public]

→ Launch unlisted (any-workspace public connection works without listing) and treat Marketplace as distribution, not a gate.

06Evidence: what was tested, sourced, and still uncertain

$ probes: live GETs with a dummy client_id, no credentials
✓ Authorize endpoint with a fake client_id → 302
https://api.notion.com/v1/oauth/authorize?client_id=probe_invalid&response_type=code&owner=user&redirect_uri=https://example.com/cb
Redirect to app.notion.com/install-integration?…
∴ Endpoint confirmed. Notion validates the client inside its install UI, not at the HTTP layer.
✓ Token endpoint (GET) → 400
https://api.notion.com/v1/oauth/token
{"code":"invalid_request_url"}
∴ Token endpoint exists and expects POST.

Sources read

  1. [notion-auth] Notion — Authorization official
  2. [notion-public] Notion — Public connections official
  3. [notion-ov] Notion — Connections overview official
  4. [n8n] n8n docs — Notion credentials third-party
  5. [composio] Composio — Managed OAuth apps directory official
  6. [probe] Live HTTP probes run by the agent (dummy client_id, no credentials) probe

Still uncertain

  • ? Notion publishes no Marketplace review timeline. 1–4 weeks is our guess.
  • ? Privacy policy / terms requirement comes from third-party docs, not Notion's current pages.
  • ? The Marketplace guidelines URL we tried returned 404, so the review criteria weren't read directly.