Notion
Notion OAuth is moderate in difficulty. You create a free "public connection" in the Notion Developer portal, and there are no OAuth scopes to justify, only capabilities set on the connection. Your own workspace can connect in under an hour. The main catch is that the Authorization URL only appears after you submit the connection for review, and Notion does not say how long that review takes. A Marketplace listing is optional and takes 5-10 business days according to Notion.
Review: The public connection must be submitted for review before its Authorization URL is issued; the Marketplace listing review is optional.
Timing: Depends on how long the unexplained public-connection review takes. An optional Marketplace listing adds 5-10 business days plus a 512px logo.
Cost: No fee is mentioned for public connections or Marketplace listings. Rate limits depend on each clinic's Notion plan.
Before you start
- for buildNotion workspace that you own (as workspace owner) to create the connection ininferreds1
- for buildCompany name✓ Iskaria has itinferreds5
- for buildWebsite, privacy policy and terms URLs✓ Iskaria has itinferreds5
- for buildSupport email (currently a personal address; a shared mailbox is recommended)✓ Iskaria has itinferreds5
- for buildRedirect URIs✓ Iskaria has itsourceds1
- for launchSquare logo/icon PNG (missing: no 512px export yet)✓ Iskaria has itsourceds2
- for launchLegal entity name (missing)✗ missing in profileinferreds2
- for launchShared support mailbox (missing)✗ missing in profileinferred
Who does what
- Implement the authorize, token and refresh flow and 429 handling
- Draft listing copy, tags and a page-sharing onboarding guide
- Try dynamic client registration against the MCP server
- Own the workspace and log in to the Developer portal
- Copy and store the client secret
- Export the 512px logo and set up the legal entity
- Submit the connection for review and, optionally, the Marketplace listing
Steps
Sign in to the Developer portal as the workspace owner, choose "create a new public connection", and set the installation scope to "Any workspace". This setting cannot be changed later.
https://app.notion.com/developers/connectionsName Iskaria Company name Iskaria Website https://iskaria.com/ Privacy policy https://iskaria.com/privacy Terms of use https://iskaria.com/terms Support email ibrahim@iskaria.com Installation scope Any workspace Under OAuth configuration, add both redirect URIs with {provider}=notion. Turn on these capabilities: read, update and insert content, read and insert comments, and user info without email.
https://app.notion.com/developers/connectionsRedirect URIs ["https://app.iskaria.com/api/oauth/{provider}/callback","http://localhost:3000/api/oauth/{provider}/callback"]https://app.iskaria.com/api/oauth/notion/callback and the localhost URI (whether localhost is accepted is unverified) Capabilities {"google":"Read Search Console, GA4 and Business Profile data for a clinic's own properties (webmasters.readonly, analytics.readonly, business.manage)","gmail":"Draft and send patient follow-up emails from the clinic's mailbox","meta":"Reply to WhatsApp, Instagram and Messenger messages for a clinic; publish the clinic's own posts","slack":"Post lead alerts and daily summaries into the clinic team's Slack","github":"Developer tooling: open issues/PRs from voice-note tasks","hubspot":"Sync leads and bookings into the clinic's CRM","default":"Let the clinic's AI assistant read and act on the clinic's own data in this app"} Copy the client ID and client secret from the Configuration tab into the server's encrypted secret store. Never put them in git or the browser.
Redirect users to https://api.notion.com/v1/oauth/authorize with client_id, redirect_uri, response_type=code, owner=user and state. Exchange the code at POST https://api.notion.com/v1/oauth/token using Basic auth (CLIENT_ID:CLIENT_SECRET). Store the access_token and refresh_token per tenant, and handle 429 responses using the Retry-After header. Hard-code the endpoints, because the REST API has no discovery document.
Run the flow, pick pages in the page picker, and confirm the agent can read and write only those pages. Also test a reauthorization by the same user.
The agent drafts the description, category and tags and an onboarding guide that tells clinics which pages to share. You review the draft and export the Systems Mark logo as a PNG.
Submit the connection. The Authorization URL field fills in only after submission. Wait for the outcome, which has no documented timeline.
Create a listing linked to the public connection. Notion says it replies by email within 5-10 business days.
https://developers.notion.com/guides/get-started/marketplace-listing
Scopes an agent typically needs
| Scope | Used for | Review tier | Evidence |
|---|---|---|---|
| Read content | Agent reads the clinic pages and databases that were shared with it | basic | inferreds4 |
| Update content | Edit lead and booking records | basic | inferreds4 |
| Insert content | Create reports and new entries | basic | inferreds4 |
| Read/insert comments | Leave notes for staff | basic | inferreds4 |
| User information without email | Attribute actions while minimising data collected | basic | inferreds4 |
What can slow you down or block approval
The Authorization URL field fills in only after the connection is submitted for review. It is unclear whether users outside your workspace can install before that.
Workaround: Submit early, once the redirect URIs and capabilities are final.
Choosing "Selected workspaces only" permanently prevents a Marketplace listing.
Workaround: Choose "Any workspace".
A clinic that shares nothing in the page picker gives the agent nothing to work with. Reauthorization by the same user skips the picker, and other users can reach a dead end.
Workaround: Add in-app guidance on which pages to share.
Limits are 600 requests/min on Business and Enterprise and 180/min on other plans, plus a shared workspace limit and about 3 requests/s for data-source queries. A Free-plan block limit applies from 2026-09-08, so agent writes may fail on Free workspaces.
There is no 512px PNG logo, so a Marketplace listing is blocked. The missing legal entity could cause brand or trademark rejections. Support currently goes to a personal email address.
Workaround: Export the logo, register the legal entity, and create support@iskaria.com.
mcp.notion.com advertises a /register endpoint with PKCE S256, so an agent may be able to register an OAuth client itself without creating an app manually. This works only on the hosted MCP server, not the REST API (api.notion.com has no discovery metadata). Admins can block MCP servers.
What we checked
| Claim | How | Result |
|---|---|---|
| Marketplace review takes 5-10 business days | marketplace-listing FAQ only | unverified |
| Rate limits are 600/min (Business/Enterprise) and 180/min (other plans), not a flat 3 rps | compared request-limits.md with truto.one | corrected |
| A Marketplace listing is optional for OAuth use | marketplace FAQ plus older authorization reference | confirmed |
| No documented test mode or user cap | searched both auth docs | unverified |
| MCP server supports dynamic client registration | probe_oauth fetched mcp.notion.com metadata (HTTP 200) | confirmed |
- What "submitted for review" requires before the Authorization URL works, and how long it takes.
- Exact fields in the public-connection form (from older docs).
- Access-token lifetime and refresh-token rotation rules.
- The capability list and whether any capability gets extra review.
- Whether localhost redirect URIs and non-exact matches are accepted.
- Whether Enterprise admins can restrict which public connections members install.
- Data residency and compliance for UAE/Kuwait clinic patient data stored in Notion.
- Marketplace 5-10 business days is Notion's own figure; no real-world reports were found.
- A third-party blog cites an older flat 3 requests/s limit; Notion's current docs (600 or 180 per minute) take precedence.
Sources
- s1Authorization (connections, PATs, OAuth flow) · official-docs · accessed 2026-10-30
“The Authorization URL field populates after a public connection is submitted for review”
- s2List on the Marketplace · official-docs · accessed 2026-10-30
“expect to hear back from our team within 5-10 business days via email”
- s3Request limits · official-docs · accessed 2026-10-30
“All other plans | 180 requests per minute (an average of 3 per second)”
- s4Get started with Notion MCP · official-docs · accessed 2026-10-30
“A workspace owner can create an MCP token with New MCP token in the Developer portal.”
- s5Authorization (older integration wording) · official-docs · accessed 2026-10-30
- s6Changelog: reauthorization · official-docs · accessed 2026-10-30
“The access token received at the end of reauthorization will be the same as the initial access token.”
- s7Changelog: public OAuth integrations · official-docs · accessed 2026-10-30
- s8Notion API architecture guide (truto.one) · community · accessed 2026-10-30
- s9probe_oauth on mcp.notion.com · our-test · accessed 2026-10-30
“registration_endpoint /register; PKCE S256; api.notion.com discovery returns 400”