OAuth app readiness guide · Docs and knowledge

Getting your Notion app ready for real users

Tested in a real setup attemptChecked 2026-10-28notion.com

Verdict. A working OAuth connection in about 4 minutes, no review. The trap is the very first choice: Notion defaults to a single-workspace API token, and the install scope you pick for OAuth is locked once the connection is created.

At a glance

The answer in one screen

Ease of creation

Easy

About 4 minutes in our test.

Ease of approval

None for OAuth

Marketplace listing is optional and separate.

Your hands-on time

10 to 20 min

Form, capabilities, then a page-sharing hint for your users.

Waiting on the provider

None

Nothing to wait for unless you list on the Marketplace.

Do you need your own app yet?

Check Composio first; your own connection is cheap here.

We could not confirm a Composio-managed Notion app. Your own connection needs no review.

Watch out: decisions you can't undo

API token is the default authentication method. Choose "OAuth" for any agent your customers will connect.
Install scope is locked after creation. Keep "Any workspace". Use a separate connection for internal testing if needed.
Deleting a connection revokes everyone. Never delete a live connection to "start fresh"; create a new one alongside.

Agent an agent can do it You needs you Waiting on the provider

Prerequisites

What to have ready

To create and connect

A Notion workspace (it becomes the connection's development workspace)
An HTTPS redirect URI with no fragments, wildcards, relative paths or public IP addresses
Agreement to Notion's Developer Terms (accepted when you create)

For approval (can take days)

Only for a Marketplace listing: listing content and images, managed under Listings

App types

Which one is right for an agent product?

API token connection

The default choice in the form.

Who can install: One workspace, shared token
Review: None
Use it for: Internal scripts and your own workspace

Recommended for agents

OAuth connection, any workspace

OAuth + Installable in: Any workspace.

Who can install: Any Notion user, each authorizes individually
Review: None
Use it for: Agent products with customers

OAuth, selected workspaces

OAuth + specific workspaces.

Who can install: Only workspaces you pick at creation
Review: None
Use it for: Pilots with named customers; not Marketplace-eligible

Integrations are now "Connections"The developer area moved to app.notion.com/developers under "Developer tools", with Connections, Workers, Personal access tokens and MCP tokens. Older guides point to notion.so/my-integrations. Tested

Creation steps

Who does what, and how long it takes

YouSign in to Notion
1 min
Then open Developer tools, Connections. notion.so/profile/integrations redirects there.
AgentNew connection, name it
30 sec
Name is shown to users.
AgentSwitch authentication to OAuth
5 sec
The form defaults to API token (decision 1).
AgentKeep Installable in: Any workspace
5 sec
Locked after creation (decision 2).
AgentAdd the redirect URI
1 min
Pick the typed value from the suggestion list or it is not saved. This tripped our agent once.
YouApprove Create connection
5 sec
This also accepts Notion's Developer Terms.
AgentNarrow capabilities
1 min
Defaults include update, insert and reading user emails. Turn off what your agent does not need.
YouCopy credentials into Composio
2 min
Client ID and secret from the Configuration tab. A ready-made authorization URL is shown too.

Total in our test: about 4 minutes of agent work and one approval.

Scopes

What each permission costs you

Notion uses capabilities set on the connection, not OAuth scope strings. Users then choose which pages to share during consent.

Agent use case	Scopes	What it costs you
Read pages and databases	`Read content`	On by default
Edit pages and database entries	`Update content`	On by default
Create pages and entries	`Insert content`	On by default
Read or add comments	`Read commentsInsert comments`	Off by default
Read people and emails	`Read user information including email addresses`	Default option; narrow it if you don't need emails

Minimal set: "Answer questions from docs" agentRead contentNo user information

Turn off update and insert, and pick "No user information".

Changing scopes later

Capabilities can be edited on the connection page.
Page access is per user: users must re-share pages if your agent needs new ones.
No review is triggered by capability changes.

Approval and distribution

Review, cost and renewal

When you need it: Never for OAuth. Only to list on the Notion Marketplace. Cost: None. Renewal: None.

OAuth

None

Works immediately for any workspace.

Marketplace

Not published

Optional listing review; timeline not documented on pages we read.

What you submit

Marketplace only: listing description, categories, images

Common rejection reasons

Connection limited to selected workspaces (not eligible)

Before approval: what works and what's capped

Build and test

Any workspace, immediately.

Limit: Agent only sees pages the user shared at consent.

First customers

Same connection.

Limit: Each user authorizes individually; only they can use it in their workspace.

Scale

Same connection, optional Marketplace listing.

Limit: Standard API rate limits.

Empty results are the top support issueUsers pick pages during consent. If they share nothing, your agent sees nothing. Tell users in your product which pages to share. Official docs

Data use and compliance

Rules that shape agent design

User-scoped access. Access is limited to the signed-in user and the pages they share.
Defaults are broad. New connections can read user email addresses unless you change it.

Design impactAsk only for capabilities you use; the consent screen shows them to every user. Tested

Common blockers

Symptom, cause, fix

Symptom	Cause	Fix
Only one workspace can use the integration	Created with API token, or OAuth limited to selected workspaces	Create a new OAuth connection with Any workspace
Agent returns nothing	User shared no pages at consent	Ask the user to reconnect and share the right pages
Redirect URI not saved	Typed value not selected from the suggestion list	Select it so it becomes a chip

Sources

Where every claim comes from

Claim	Source
API token is the default; OAuth must be chosen	Tested in our setup
Install scope read-only after creation	Tested in our setup
Default capabilities include user emails	Tested in our setup
No review needed for OAuth	Tested in our setup
Token lifetime and refresh	Not verified
Marketplace review timeline	Not verified

All sources

Notion: Public connections developers.notion.com
Notion: Authorization developers.notion.com