Skip to main content
Before your users can connect their Notion workspaces, Notion needs a public integration that you own. It’s the same kind of integration as the internal one you’d make for yourself, but with OAuth turned on. Each user chooses which pages to share on Notion’s own consent screen. It takes about three minutes. Only connecting your own workspace? Set up Notion is shorter: an internal integration, its secret, and the pages it may read. Every Notion link below opens in a new tab, so this page stays where you left it.
1

Start a new integration

Open notion.so/profile/integrations and click New integration.
Notion's Integrations page, with Internal and Public tabs and a Create a new integration tile above an existing integration.
2

Make it public

The New Integration form: integration name Example App, an icon, type Public, associated workspace Example Workspace, and company name Example Inc.
  • Integration name and Icon: what your users see on the consent screen.
  • Type: Public. An internal integration can’t use OAuth, and a public one isn’t tied to a single workspace.
  • Associated workspace: where you’ll manage it. Users in any workspace can still connect.
  • Company name, Website, and the privacy policy and terms links further down: Notion requires them for a public integration and shows them to your users.
3

Add your redirect URI

Further down the same form, under OAuth domains & URIs, add your app’s callback route under Redirect URIs, then click Create.
The OAuth domains & URIs section with https://app.example.com/oauth/notion/callback entered as a redirect URI.
Notion is strict about this URI. It has to use HTTPS, match character for character, and have no fragment, wildcard or relative path.
4

Tick the capabilities the tools use

On the integration’s Configuration tab, under Capabilities, tick what the pack’s tools declare:
  • Read content, Update content and Insert content
  • Read comments and Insert comments
  • Read user information, with or without email addresses
The Capabilities section: Read, Update and Insert content ticked, the two comment capabilities unticked, and Read user information including email addresses selected.
The screenshot leaves the two comment capabilities off. Tick them if you hand out the comment tools, which answer 403 without them. Notion lists every capability on the consent screen, so leave off any your tools don’t use. Save changes.
5

Copy the client ID and secret

Still on Configuration, copy the OAuth Client ID, then click Show next to OAuth Client Secret and copy that too.
The Edit Integration page for Example App: the OAuth client ID, a masked OAuth client secret with a Show link, and the authorization URL.
You don’t need the Authorization URL shown below them. flow.authorize() builds the same link, with state and PKCE added.
6

Connect a workspace

Your app’s “Connect Notion” button opens that link. Notion shows the capabilities you ticked, and the user clicks Select pages to choose what your app can reach.
Notion's consent screen: Connect with Example App, the permissions it has (view, edit and create content in pages you select, view workspace users and their emails), and Cancel and Select pages buttons.
The pages the user picks here are all the integration can see. A page they didn’t pick answers object_not_found, and if they picked nothing, search comes back empty. The pages can be changed later, from the integration’s entry under Settings → Connections in their workspace.The server constant and the per-user client are in the Notion provider page. The link asks for no scopes, since the capabilities you ticked play that role, and Notion’s token endpoint takes JSON rather than a form. The constant declares both.

​
When it does not work

The flow sent a URI that isn’t listed under Redirect URIs, character for character. A trailing slash is enough to break the match.
The user connected but shared no pages, or not the ones you expect. They can add pages from the integration’s entry under Settings → Connections.
The integration doesn’t have Read comments or Insert comments. Tick them under Capabilities, then have the user connect again so their grant includes them.
  • Notion OAuth — the server constant and the per-user client
  • Getting the grant — the two routes, state and PKCE, inside your app
  • Notion — the pack, and how a database differs from the table inside it
  • Set up Notion — your own workspace, with an internal integration