# Notion: OAuth app setup and approval
Self-serve · Partial · updated 27 Oct 2026 · https://oauth-guide.akshatsethi.com/apps/notion

> 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.

- **Your hands-on work:** 30–90 min
- **Waiting on Notion:** None
- **First user can connect:** Today, in about 30 minutes
- **Why Self-serve:** 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.
- **Using Composio?** 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.

## Path to launch
### Build: Your workspace
- Who can connect: You, from your development workspace or any workspace you selected
- What users see: Notion's consent screen with your connection name, the capabilities it asks for, and a page picker
- Effort: 30–60 min · Wait: None
- Next: Create the connection with the 'Any workspace' installation scope. If the portal asks you to, submit it so the authorization URL fills in.
- _(Docs [1, 2], medium confidence)_

### Launch: Public launch
- Who can connect: 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.
- What users see: The same consent screen and page picker. A Marketplace listing is optional and only changes whether users can find you in Notion.
- Effort: 0–30 min · Wait: None
- _(Docs [2, 3], medium confidence)_

## Before you start
- [ ] **A Notion workspace you own** (You). Notion requires workspace ownership to create internal connections. StackOne reports the same for public connections. _(Community [1, 5], medium confidence)_
- [ ] **Your OAuth redirect URI** (Agent). You must enter at least one redirect URI when you create the connection. _(Docs [2], medium confidence)_
- [ ] **Connection logo** (You). StackOne's setup guide marks the logo as required on the creation form. _(Community [5], medium confidence)_
- [ ] **Marketplace listing assets (optional)** (You). Only needed if you want to appear in the Marketplace: a name, description, category, tags, images and a logo. _(Docs [3], medium confidence)_

## Steps
1. **Open Public connections in the Developer portal** (You, 2–5 min). Sign in to Notion as a workspace owner, open the Developer portal and choose Public connections under Build. _(Docs [2], medium confidence)_
   - Go to app.notion.com/developers/connections
   - In the sidebar, choose Build > Public connections
   - Agent: Once you're signed in, an agent can do the rest of the form.
2. **Create the public connection** (Agent, 5–15 min). Click Create new connection. Enter the name, development workspace, logo, your redirect URI(s) and the installation scope. _(Docs [2, 5])_
   - 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
   - Agent: An agent can fill in the form and copy in the redirect URI. You supply the logo file.
   - Watch out: 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.
3. **Choose content, comment and user capabilities** (Agent, 2–5 min). 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. _(Docs [2, 5], medium confidence)_
   - Enable the content capabilities you need
   - Enable comment capabilities if needed
   - Enable 'Read user information including email addresses' if you need the email
   - Save
   - Watch out: Users see these capabilities on the consent screen, so asking for more than you need can make them hesitate.
4. **Copy the client ID and secret into your OAuth client** (You, 2–5 min). The OAuth client ID and secret are in the Configuration tab. Store the secret outside source code. _(Docs [1, 2], medium confidence)_
   - Copy the OAuth client ID
   - Reveal the OAuth client secret and store it in your secret manager or OAuth client
   - Agent: An agent can copy the client ID. You handle the client secret yourself.
5. **Configure your OAuth client's endpoints** (Agent, 5–15 min). 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. _(Docs [1], medium confidence)_
   - 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
   - Watch out: 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.
6. **Connect your own workspace and test** (Agent, 5–10 min). Run the flow, pick some pages and confirm you get an access token, a refresh token and a workspace_id back. _(Docs [1, 2], medium confidence)_
   - Agent: An agent can drive the test while you're signed in to Notion.
   - Watch out: The connection only sees pages the user shared in the picker. Each workspace member has to authorize it separately.
7. **Submit the connection if the authorization URL is empty** (You, 5–15 min). 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. _(Docs [1], low confidence)_
   - Agent: An agent can check the Configuration tab. You make the submission.
   - Watch out: 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.
8. **Optionally submit a Marketplace listing** (You, 20–60 min). 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. _(Docs [3, 4], medium confidence)_
   - Write the name, description, category and tags
   - Upload images and a logo
   - Link the public connection and submit from Listings > Connections
   - Agent: An agent can draft the listing. You submit it.
   - Watch out: Listings get rejected for brand or trademark issues and quality concerns. You can revise and resubmit.

## When you get stuck
- **Users from other workspaces can't install the connection.** 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. _(Docs [2, 3], medium confidence)_
- **The Authorization URL field in the Configuration tab is blank.** 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. _(Docs [1], medium confidence)_
- **You can't create a connection.** You're probably not a workspace owner. Fix: Have a workspace owner create it, or create a workspace you own. _(Community [1, 5], medium confidence)_

## Not confirmed yet
- **Does a public connection have to be submitted or approved before users outside your workspace can authorize it?** 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. To resolve: Create the connection, then authorize it from a second Notion account in a different workspace before submitting anything.
- **Are company name, website, privacy policy, terms and support email still required?** Older tutorials list these fields. The current public connections guide doesn't mention them. To resolve: Check the live creation form in the Developer portal.
- **How long do access tokens last?** The docs describe refresh tokens but don't give an expiry. To resolve: Look at the token response, or test how long a token keeps working.

## Sources
1. [Authorization](https://developers.notion.com/guides/get-started/authorization) (Notion Developers). Not yet checked
2. [Public connections](https://developers.notion.com/guides/get-started/public-connections) (Notion Developers). Not yet checked
3. [List on the Marketplace](https://developers.notion.com/guides/get-started/marketplace-listing) (Notion Developers). Not yet checked
4. [Publishing integrations to Notion's Integration Gallery](https://developers.notion.com/docs/publishing-integrations-to-notions-integration-gallery) (Notion Developers). Not yet checked
5. [Notion OAuth 2.0 connector profile](https://docs.stackone.com/connectors/notion/guides/connector-profile/oauth-2-0) (StackOne docs). Checked 27 Oct 2026
6. [Managed auth toolkits](https://docs.composio.dev/toolkits/managed-auth.md) (Composio docs). Checked 27 Oct 2026
7. [Getting started](https://developers.notion.com/docs/getting-started) (Notion Developers). Checked 27 Oct 2026

Wrong or out of date? POST https://oauth-guide.akshatsethi.com/api/reports with {"app": "notion", "step": 2, "message": "what you saw"} (step is optional), or call the report_problem MCP tool. The next research run checks it.
Followed it? Say how it went: POST https://oauth-guide.akshatsethi.com/api/reports with {"app": "notion", "outcome": "worked" | "waiting" | "stuck", "step": 3, "message": "what happened"}, or call the report_setup MCP tool.