OAuth Readiness
Back to all apps

Notion

Library guide, researched by Claude Code agents, checked 2026-10-19. Setup tested by hand on 2026-10-19.

Notion lets you create a public (OAuth) connection yourself in the Developer portal and use it with any Notion workspace right away; no Notion review is needed unless you want a Marketplace listing, which takes about 5-10 business days. The work that matters is designing around page-level access: each user picks which pages the connection can see during OAuth, and anything they did not pick is invisible to your agent.

Tier 1: Instant

Hands-on work
0.5–3 hours
Waiting for approval
None
Confidence
high

Assumes: A public connection with installation scope 'Any workspace' that any external Notion user can authorize via OAuth 2.0, with the capabilities an AI agent typically needs: Read content, Update content, Insert content, Read comments, Insert comments, and User information without email addresses. Not listed on the Notion Marketplace.

10 min1 hour1 workday1 week1 month6 months

Solid dark bar: your hands-on work. Amber: the minimum wait. Hatched: the range sources disagree on, or an open-ended wait.[2][3][6]

Why tier 1? Nothing gates this path.
The tier is computed from these seven facts by a fixed rule, not chosen by the AI. High: the gates that set this tier are backed by the provider's own docs or our own test.
Self-serve credentialsYesA public connection is created in the Developer portal; the OAuth client ID and client secret appear in its Configuration tab. You must be a workspace owner of the development workspace (a free personal workspace works, since you own it).[6][7][17]
Limits until reviewedNoNotion documents no user cap, test-user list or 'unverified app' screen for public connections. The 'Selected workspaces only' scope is a choice you make, not a dev-mode limit. One line in the Authorization guide says the Authorization URL field 'populates after a public connection is submitted for review', which seems to be left over from the older 'make public' flow; the current Public connections and Marketplace guides describe no review before use.[2][10]
Provider reviewNoNotion's security/listing review applies only to Marketplace listings. Notion's own FAQ says a public connection can be used through its OAuth flow without being listed. The Authorization guide's 'submitted for review' wording (s10) conflicts with this and is the main thing to confirm by hand. Confirmed by our test: the authorization URL was shown immediately after creating the connection, with no submission step.[1][2][10][17]
Security assessmentNoNo third-party assessment (like Google CASA) is mentioned. Notion runs its own security review, and only for Marketplace listings.[1]
Business verificationNoNo legal-entity verification is documented. The older public-integration form (described by Make) asks for a company name but says you may use your own name.[14][17]
Mandatory feesNoNone of the docs reviewed mention a fee for creating, using or listing a public connection.[17]
Partner or paid accessNoThe REST API and public connections are open to any Notion user who owns a workspace; there is no partner program or paid tier. Rate limits depend on the installing workspace's plan.[16][12][17]

You can start today without any of this. Composio already provides a managed OAuth app for Notion (notion, notion_mcp), so users can connect while you work through your own app. You need your own app for your brand on the consent screen, your own rate limits, or scopes beyond the defaults. Managed auth list

If your case is different

Marketplace listing
Optional. Only 'Any workspace' connections are eligible. You submit a listing (name, description, category, images, logo) and Notion reviews it; expect a reply within 5-10 business days, and rejections can be for brand/trademark, quality, or baseline-criteria reasons.
Internal connection (one workspace)
No OAuth: a workspace owner creates it and gets a static API token right away. Pages are shared with it from the Content access tab or the page's Add connections menu. It acts as its own bot user, not as the person who connected it. Not usable by other workspaces.
Personal access token
For scripts or tools acting as one user: no OAuth and no page picker, it uses the creator's own page permissions, and it expires after at most one year. Not a way for other users to connect your app.
Selected workspaces only
A public connection restricted to workspaces you pick when you create it. It can never be listed on the Marketplace, and the scope can't be changed later, so you would need a new connection.

Steps

Agent steps an AI agent can do or draft for you. You steps that need your identity, accounts, legal authority or a real demo.

  1. Get a Notion workspace you own

    You

    Sign in to Notion and use (or create) a workspace where you are a workspace owner. Only owners can create connections.[7]

  2. Create a public connection

    You

    In the Developer portal go to Build > Public connections > Create new connection. Enter the name and development workspace, and choose the installation scope 'Any workspace'. The scope can't be changed later.[5][6]

  3. Fill redirect URI(s) and capabilities

    Agent

    Add your OAuth callback URL. Select the minimum capabilities you need: Read/Update/Insert content, Read/Insert comments, and a user-information level. Changing capabilities later forces existing users to re-authenticate.[6][11]

  4. Add public-facing details only if you list on the Marketplace

    Agent

    In our test, creating a public connection didn't ask for company name, privacy policy, terms or support email. Those apply to an optional Marketplace listing.[14][17]

  5. Copy client ID, client secret and authorization URL

    You

    From the Configuration tab, store the OAuth client ID and secret in a secret manager. The authorization URL is https://api.notion.com/v1/oauth/authorize with owner=user and response_type=code.[6][10]

  6. Implement the code exchange and refresh

    Agent

    POST the code to https://api.notion.com/v1/oauth/token with HTTP Basic auth (client_id:client_secret). Store access_token, refresh_token, bot_id and workspace_id. Every refresh returns a new refresh token as well.[15]

  7. Test with a second workspace

    You

    Authorize from a workspace other than the development one, select pages in the page picker, and confirm API calls only see the shared pages.[8][9]

What you will need

  • Notion account that is a workspace owner of the development workspace[7]
  • HTTPS redirect URI(s) for the OAuth callback[6]
  • Installation scope chosen at creation ('Any workspace' for an app open to any user)[5]
  • Possibly a company name, website, privacy policy URL, terms of use URL and support email (asked for in the older public-integration form; not confirmed for the current portal)[14]
  • For a Marketplace listing only: listing name, description, category, tags, images and logo[3]

Nuances that catch people out

  • Access is per page, not per workspace. Your agent only sees pages the user picked in the page picker (and their children). New pages outside those are invisible until the user shares them through the Add connections menu or runs the picker again.[9]
  • Each user authorizes separately. After one user connects, only that user can interact with or share pages with the connection, so teammates in the same workspace must each go through OAuth.[8]
  • Installation scope can't be changed after creation. Picking 'Selected workspaces only' rules out the Marketplace for good.[5]
  • Changing capabilities later forces every existing user to re-authenticate.[11]
  • On Enterprise plans, workspace owners can restrict which connections members may install, so some users will need admin approval.[13]
  • Rate limits apply per connection and per workspace, sized by the workspace's plan: 180 requests per minute on most plans, 600 on Business/Enterprise. A 429 error returns rate_limited.[12]
  • Every refresh rotates the refresh token, so store the new pair each time or the next refresh will fail.[15]
  • The redirect URI field doesn't validate typos: a URL with a trailing period was saved without error in our test, which would break sign-ins. Double-check it.[17]

If you get stuck or rejected

API calls return errors or empty results after a successful OAuth.
The user didn't share those pages. Ask them to pick a parent page in the page picker, or add the connection from the page's ••• > Connections menu.[9]
A user can't find or install the connection in their workspace.
Their Enterprise workspace owner may limit installable connections. Ask the owner to allow it.[13]
Marketplace listing rejected.
Read the emailed feedback (common causes: brand/trademark, quality, baseline criteria), fix the listing and resubmit. Your OAuth flow keeps working while you do.[4][2]
Created the connection as 'Selected workspaces only' and now need open installs or a listing.
Create a new public connection with 'Any workspace'. The scope can't be edited.[5]

Evidence

What we tested by hand

We created a public OAuth connection (installable in any workspace) from the Notion desktop app with Read content only. The client ID, client secret and a ready-made authorization URL appeared immediately. Notion asked for no company details, privacy policy or terms, and there was no review step.

StepDocs saidWe sawMatch
Naming and formIntegrations are now called connections; public ones can be installed in any workspace.The form is titled New connection: "Choose a single or multi-workspace scope." Authentication is OAuth, and Installable in is set to Public.Yes
Company and legal detailsOlder flows asked for company name, website, privacy policy, terms and support email (secondary source only).None of these were asked for when creating a public connection. They only matter for an optional Marketplace listing, shown as Unpublished.No
Review before external usersNotion's Authorization guide says the authorization URL populates after the connection is submitted for review; other official pages say no review is needed outside the Marketplace.The authorization URL was shown immediately on creation. There was no submit-for-review step. The Authorization guide is out of date.No
Redirect URIThe form says users are redirected to "one of these HTTPS URLs".http://localhost:3100/callback was accepted. A typo with a trailing period was also saved without any validation error.No
CredentialsClient ID and secret are on the Configuration tab.Client ID, client secret and the authorization URL were all on the connection page straight away.Yes

What we could not verify

  • Access token lifetime for public connections. Refresh tokens are documented, but none of the pages reviewed state an expiry for REST API access tokens.

Sources

Each quote was checked by code against the live page. “Not found on page” means the quote may be paraphrased, so treat that claim with care.

  1. Overview - Notion Docs
    Provider docsQuote found on pagechecked 2026-10-19
    You can create and use a public connection without listing it.
  2. List on the Marketplace - Notion Docs
    Provider docsQuote found on pagechecked 2026-10-19
    Public connections work independently of Marketplace listings. Listing on the Marketplace is optional and helps your connection reach a wider audience, but your connection can be used via its OAuth flow without being listed.
  3. List on the Marketplace - Notion Docs
    Provider docsQuote found on pagechecked 2026-10-19
    After submission, expect to hear back from our team within 5-10 business days via email.
  4. List on the Marketplace - Notion Docs
    Provider docsQuote found on pagechecked 2026-10-19
    Connections are rejected for various reasons, from brand/trademark issues to quality concerns to situations where the baseline connection criteria isn't met.
  5. Public connections - Notion Docs
    Provider docsQuote found on pagechecked 2026-10-19
    Installation scope is set once, at creation time, and can't be changed afterward.
  6. Public connections - Notion Docs
    Provider docsQuote found on pagechecked 2026-10-19
    The client ID identifies your connection to Notion during the OAuth flow, and the client secret proves your connection is who it claims to be.
  7. Authorization - Notion Docs
    Provider docsQuote found on pagechecked 2026-10-19
    You are required to be a workspace owner to create a connection.
  8. Authorization - Notion Docs
    Provider docsQuote found on pagechecked 2026-10-19
    After a user authorizes a public connection, only that user is able to interact or share pages and databases with the connection.
  9. Authorization - Notion Docs
    Provider docsQuote found on pagechecked 2026-10-19
    Parent pages can be selected to quickly provide access to child pages, as giving access to a parent page will provide access to all available child pages.
  10. Authorization - Notion Docs
    Provider docsQuote found on pagechecked 2026-10-19
    The Authorization URL field populates after a public connection is submitted for review
  11. Connection capabilities - Notion Docs
    Provider docsQuote found on pagechecked 2026-10-19
    For public connections, users will need to re-authenticate with a connection if the capabilities are changed in the time since the user last authenticated with the connection.
  12. Request limits - Notion Docs
    Provider docsQuote found on pagechecked 2026-10-19
    The Notion API enforces two rate limits: a per-connection limit and a per-workspace limit.
  13. Add & manage connections in Notion - Notion Help Center
    Provider docsQuote found on pagechecked 2026-10-19
    On Enterprise plans, workspace owners can restrict which connections members are allowed to install.
  14. Notion - Make Apps Documentation
    Secondary sourceQuote found on pagechecked 2026-10-19
    Privacy policy URL address used to link to your integration’s privacy policy in your integration page and authentication screens.
  15. Authorization - Notion Docs
    Provider docsQuote found on pagechecked 2026-10-19
    Refreshing an access token will generate a new access token and a new refresh token.
  16. Overview - Notion Docs
    Provider docsQuote found on pagechecked 2026-10-19
    Public connections use OAuth 2.0 for authentication.
  17. Hands-on test: creating a public OAuth connection (2026-10-19)
    Tested by uschecked 2026-10-19