{"slug":"notion","name":"Notion","domain":"notion.so","category":"Docs & wiki","summary":"Reaching public launch is mostly self-serve. You create a public connection in Notion's Developer portal, get an OAuth client ID and secret, and Notion's docs say the connection works through OAuth without a Marketplace listing. The only formal review is the optional Marketplace listing, which takes 5–10 business days. One line in the docs (the authorization URL field fills in after you submit for review) means you should check in the portal whether submitting is needed before outside workspaces can install.","tier":"self-serve","tierReason":"Notion's docs say public connections work independently of Marketplace listings, so OAuth installs don't depend on the reviewed listing. Confidence is medium because of the wording about submitting for review.","quality":"generated","updatedAt":"2026-10-27","composio":{"status":"managed","note":"Composio has a managed Notion OAuth app, so you can prototype before you create your own public connection. Register your own before launch so your connection name and logo appear on Notion's consent screen. The separate NOTION_MCP toolkit requires your own OAuth app.","toolkit":"NOTION"},"totals":{"effort":{"min":30,"max":90,"unit":"minutes"},"wait":{"min":0,"max":0,"unit":"days"},"firstConnection":"Today, in about 30 minutes"},"stages":[{"id":"build","name":"Your workspace","whoCanConnect":"You, from your development workspace or any workspace you selected","userSees":"Notion's consent screen with your connection name, the capabilities it asks for, and a page picker","effort":{"min":30,"max":60,"unit":"minutes"},"wait":{"min":0,"max":0,"unit":"minutes"},"unlock":"Create the connection with the 'Any workspace' installation scope. If the portal asks you to, submit it so the authorization URL fills in.","evidence":{"kind":"docs","sources":["s1","s2"],"confidence":"medium"}},{"id":"launch","name":"Public launch","whoCanConnect":"Any Notion user who has full access to the pages they share. Connections set to 'Selected workspaces only' stay limited to the workspaces you chose.","userSees":"The same consent screen and page picker. A Marketplace listing is optional and only changes whether users can find you in Notion.","effort":{"min":0,"max":30,"unit":"minutes"},"wait":{"min":0,"max":0,"unit":"days"},"unlock":null,"evidence":{"kind":"docs","sources":["s2","s3"],"confidence":"medium"}}],"requirements":[{"id":"workspace-owner","label":"A Notion workspace you own","detail":"Notion requires workspace ownership to create internal connections. StackOne reports the same for public connections.","stage":"build","actor":"you","evidence":{"kind":"community","sources":["s1","s5"],"confidence":"medium"}},{"id":"redirect-uri","label":"Your OAuth redirect URI","detail":"You must enter at least one redirect URI when you create the connection.","stage":"build","actor":"agent","evidence":{"kind":"docs","sources":["s2"],"confidence":"medium"}},{"id":"logo","label":"Connection logo","detail":"StackOne's setup guide marks the logo as required on the creation form.","stage":"build","actor":"you","evidence":{"kind":"community","sources":["s5"],"confidence":"medium"}},{"id":"listing-assets","label":"Marketplace listing assets (optional)","detail":"Only needed if you want to appear in the Marketplace: a name, description, category, tags, images and a logo.","stage":"launch","actor":"you","evidence":{"kind":"docs","sources":["s3"],"confidence":"medium"}}],"steps":[{"id":"open-portal","title":"Open Public connections in the Developer portal","actor":"you","stage":"build","time":{"min":2,"max":5,"unit":"minutes"},"detail":"Sign in to Notion as a workspace owner, open the Developer portal and choose Public connections under Build.","actions":["Go to app.notion.com/developers/connections","In the sidebar, choose Build > Public connections"],"agentNote":"Once you're signed in, an agent can do the rest of the form.","link":{"label":"Notion Developer portal","url":"https://app.notion.com/developers/connections"},"evidence":{"kind":"docs","sources":["s2"],"confidence":"medium"}},{"id":"create-connection","title":"Create the public connection","actor":"agent","stage":"build","time":{"min":5,"max":15,"unit":"minutes"},"detail":"Click Create new connection. Enter the name, development workspace, logo, your redirect URI(s) and the installation scope.","actions":["Enter the connection name and pick a development workspace","Upload a logo","Add your OAuth client's redirect URI","Set Installable in to 'Any workspace' if users outside your chosen workspaces should be able to install it"],"agentNote":"An agent can fill in the form and copy in the redirect URI. You supply the logo file.","gotcha":"You can't change the installation scope after creation. 'Selected workspaces only' blocks other workspaces and Marketplace listing, so to switch you have to create a new connection.","link":{"label":"Public connections guide","url":"https://developers.notion.com/guides/get-started/public-connections"},"evidence":{"kind":"docs","sources":["s2","s5"],"confidence":"high"}},{"id":"set-capabilities","title":"Choose content, comment and user capabilities","actor":"agent","stage":"build","time":{"min":2,"max":5,"unit":"minutes"},"detail":"Turn on only the capabilities you need, such as reading, updating or inserting content. Turn on the capability to read user information if your app needs the user's email.","actions":["Enable the content capabilities you need","Enable comment capabilities if needed","Enable 'Read user information including email addresses' if you need the email","Save"],"gotcha":"Users see these capabilities on the consent screen, so asking for more than you need can make them hesitate.","evidence":{"kind":"docs","sources":["s2","s5"],"confidence":"medium"}},{"id":"copy-credentials","title":"Copy the client ID and secret into your OAuth client","actor":"you","stage":"build","time":{"min":2,"max":5,"unit":"minutes"},"detail":"The OAuth client ID and secret are in the Configuration tab. Store the secret outside source code.","actions":["Copy the OAuth client ID","Reveal the OAuth client secret and store it in your secret manager or OAuth client"],"agentNote":"An agent can copy the client ID. You handle the client secret yourself.","evidence":{"kind":"docs","sources":["s1","s2"],"confidence":"medium"}},{"id":"configure-client","title":"Configure your OAuth client's endpoints","actor":"agent","stage":"build","time":{"min":5,"max":15,"unit":"minutes"},"detail":"The authorize URL is https://api.notion.com/v1/oauth/authorize with response_type=code and owner=user. The token URL is https://api.notion.com/v1/oauth/token, using HTTP Basic auth with the client ID and secret.","actions":["Set the authorize URL with client_id, redirect_uri, response_type=code and owner=user","Set the token URL. Send the token request as JSON with Basic auth","Store the new refresh token after every refresh, because each refresh replaces it"],"gotcha":"Notion has no scopes parameter. Access depends on the capabilities you set and the pages the user picks. If you register more than one redirect URI, include redirect_uri in the token request.","link":{"label":"Authorization guide","url":"https://developers.notion.com/guides/get-started/authorization"},"evidence":{"kind":"docs","sources":["s1"],"confidence":"medium"}},{"id":"test-connection","title":"Connect your own workspace and test","actor":"agent","stage":"build","time":{"min":5,"max":10,"unit":"minutes"},"detail":"Run the flow, pick some pages and confirm you get an access token, a refresh token and a workspace_id back.","agentNote":"An agent can drive the test while you're signed in to Notion.","gotcha":"The connection only sees pages the user shared in the picker. Each workspace member has to authorize it separately.","evidence":{"kind":"docs","sources":["s1","s2"],"confidence":"medium"}},{"id":"submit-if-needed","title":"Submit the connection if the authorization URL is empty","actor":"you","stage":"launch","time":{"min":5,"max":15,"unit":"minutes"},"detail":"Notion's docs say the Authorization URL field fills in after a public connection is submitted for review. If the field is empty and outside users can't install, submit from the portal.","agentNote":"An agent can check the Configuration tab. You make the submission.","gotcha":"It's unclear whether this submission blocks installs or only fills in a convenience URL. You can build the authorize URL yourself from the client ID.","evidence":{"kind":"docs","sources":["s1"],"confidence":"low"}},{"id":"marketplace-listing","title":"Optionally submit a Marketplace listing","actor":"you","stage":"launch","time":{"min":20,"max":60,"unit":"minutes"},"detail":"To appear in Notion's Marketplace, create a listing under Listings, link your 'Any workspace' connection and submit it. Notion replies by email within 5–10 business days.","actions":["Write the name, description, category and tags","Upload images and a logo","Link the public connection and submit from Listings > Connections"],"agentNote":"An agent can draft the listing. You submit it.","gotcha":"Listings get rejected for brand or trademark issues and quality concerns. You can revise and resubmit.","link":{"label":"Marketplace listing guide","url":"https://developers.notion.com/guides/get-started/marketplace-listing"},"evidence":{"kind":"docs","sources":["s3","s4"],"confidence":"medium"}}],"blockers":[{"symptom":"Users from other workspaces can't install the connection","cause":"The connection was created with 'Selected workspaces only', and that setting can't be changed.","fix":"Create a new public connection with 'Any workspace' and switch your OAuth client to its credentials.","evidence":{"kind":"docs","sources":["s2","s3"],"confidence":"medium"}},{"symptom":"The Authorization URL field in the Configuration tab is blank","cause":"Notion fills it in only after the public connection is submitted for review.","fix":"Build the authorize URL yourself from your client ID and redirect URI, or submit the connection in the portal.","evidence":{"kind":"docs","sources":["s1"],"confidence":"medium"}},{"symptom":"You can't create a connection","cause":"You're probably not a workspace owner.","fix":"Have a workspace owner create it, or create a workspace you own.","evidence":{"kind":"community","sources":["s1","s5"],"confidence":"medium"}}],"unknowns":[{"question":"Does a public connection have to be submitted or approved before users outside your workspace can authorize it?","why":"The docs say connections work without a Marketplace listing, but also that the authorization URL only fills in after submission for review. No developer reports from 2026 settle it.","resolve":"Create the connection, then authorize it from a second Notion account in a different workspace before submitting anything."},{"question":"Are company name, website, privacy policy, terms and support email still required?","why":"Older tutorials list these fields. The current public connections guide doesn't mention them.","resolve":"Check the live creation form in the Developer portal."},{"question":"How long do access tokens last?","why":"The docs describe refresh tokens but don't give an expiry.","resolve":"Look at the token response, or test how long a token keeps working."}],"handoff":{"agentCan":["Fill in the public connection form and redirect URIs","Set capabilities","Copy the client ID and configure your OAuth client's endpoints","Run and check a test connection","Draft Marketplace listing text"],"youMust":["Sign in as a Notion workspace owner","Provide the logo and handle the client secret","Choose the installation scope, which can't be changed later","Submit the connection or Marketplace listing for review"]},"sources":[{"id":"s1","title":"Authorization","url":"https://developers.notion.com/guides/get-started/authorization","publisher":"Notion Developers","kind":"official","checkedAt":null},{"id":"s2","title":"Public connections","url":"https://developers.notion.com/guides/get-started/public-connections","publisher":"Notion Developers","kind":"official","checkedAt":null},{"id":"s3","title":"List on the Marketplace","url":"https://developers.notion.com/guides/get-started/marketplace-listing","publisher":"Notion Developers","kind":"official","checkedAt":null},{"id":"s4","title":"Publishing integrations to Notion's Integration Gallery","url":"https://developers.notion.com/docs/publishing-integrations-to-notions-integration-gallery","publisher":"Notion Developers","kind":"search","checkedAt":null},{"id":"s5","title":"Notion OAuth 2.0 connector profile","url":"https://docs.stackone.com/connectors/notion/guides/connector-profile/oauth-2-0","publisher":"StackOne docs","kind":"community","checkedAt":"2026-10-27"},{"id":"s6","title":"Managed auth toolkits","url":"https://docs.composio.dev/toolkits/managed-auth.md","publisher":"Composio docs","kind":"composio","checkedAt":"2026-10-27"},{"id":"s7","title":"Getting started","url":"https://developers.notion.com/docs/getting-started","publisher":"Notion Developers","kind":"official","checkedAt":"2026-10-27"}],"feedback":{}}