Public integrations

Learn how public integrations work, how users authorize them, and how to create one.

What is a public integration?

A public integration is an OAuth integration that users install into their Notion workspaces. Unlike internal integrations, which are scoped to a single workspace with a static token, public integrations follow the OAuth 2.0 protocol: each user who authorizes the integration receives their own access token, scoped to their workspace.

When you create a public integration, you also choose its installation scope — either Any workspace (Marketplace-eligible) or Selected workspaces only (not Marketplace-eligible).

In this guide, you’ll learn:

• How public integrations differ from internal integrations
• How installation scope controls who can install your integration
• How users authorize a public integration via OAuth
• How to create a public integration in the Creator dashboard

How public integrations differ from internal integrations

The key differences come down to scope, identity, and how access is granted:

• Scope: Internal integrations work in one workspace; public integrations can install into many. Installation scope controls which workspaces are eligible.
• Identity: Internal integrations operate as their own bot user with permissions independent of any specific person. Public integrations act on behalf of the individual user who authorized them — the access token is tied to that user.
• Page access: Internal integrations require workspace members to manually share pages via the “Add connections” menu. Public integrations use the OAuth page picker, where users choose which pages to grant access to during the authorization flow.

For a full comparison, see the comparison table in the Overview.

Installation scope

Every public integration has an installation scope that controls which workspaces can install it. You pick the scope when you create the integration.

Scope	Who can install	Marketplace eligible
Any workspace	Any Notion user, in any workspace.	Yes
Selected workspaces only	Only the workspaces you approve at creation time.	No

Installation scope is set once, at creation time, and can’t be changed afterward. If you pick Selected workspaces only and later want to list on the Marketplace, you’ll need to create a new integration.

How users authorize a public integration

When a user wants to use your public integration, they go through an OAuth authorization flow:

1. The user visits the integration’s authorization URL. You’ll find this URL in the Configuration tab of your integration in the Creator dashboard.

2. Notion presents a prompt describing the integration’s capabilities — what it will be able to do in the user’s workspace.

3. The user selects which pages to grant the integration access to using the page picker.

4. After the user approves, Notion redirects them to your redirect URI with a temporary authorization code.

5. Your integration exchanges the code for an access token, which is used for all subsequent API requests on behalf of that user.

Public integrations can also offer a Notion template during the auth flow. If configured, users can choose to duplicate the template into their workspace instead of selecting existing pages. See the Authorization guide for details on configuring templates.

After a user authorizes a public integration, only that user can interact with the integration in their workspace. If multiple members in a workspace want to use the same public integration, each user needs to complete the authorization flow individually.

Creating a public integration

1. Navigate to the Creator dashboard.

2. In the Build section of the sidebar, select Public integrations.

3. Click Create new integration and fill in the required fields, including:

   • Integration name and associated workspace
   • Redirect URI(s) for the OAuth flow
   • Installation scope (if you pick Selected workspaces only, choose the approved workspaces from the list that appears)
   • Integration capabilities (read content, update content, insert content, etc.)
4. After creation, visit the Configuration tab to retrieve your OAuth client ID and OAuth client secret. The client ID identifies your integration to Notion during the OAuth flow, and the client secret proves your integration is who it claims to be. You’ll need both when your server exchanges the authorization code for an access token. See the Authorization guide for the full implementation.

Marketplace listing details (such as descriptions, categories, and images) are managed separately through the Listings section of the Creator dashboard. See List on the Marketplace for details.

Next steps

Set up OAuth authorization

Implement the full OAuth 2.0 flow for your public integration.

Preparing for users

Automate user onboarding after they install your integration.