What is a public connection?
A public connection is an OAuth connection that users install into their Notion workspaces. Unlike internal connections, which are scoped to a single workspace with a static token, public connections follow the OAuth 2.0 protocol: each user who authorizes the connection receives their own access token, scoped to their workspace. When you create a public connection, 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 connections differ from internal connections
- How installation scope controls who can install your connection
- How users authorize a public connection via OAuth
- How to create a public connection in the Creator dashboard
How public connections differ from internal connections
The key differences come down to scope, identity, and how access is granted:- Scope: Internal connections work in one workspace; public connections can install into many. Installation scope controls which workspaces are eligible.
- Identity: Internal connections operate as their own bot user with permissions independent of any specific person. Public connections act on behalf of the individual user who authorized them — the access token is tied to that user.
- Page access: Internal connections require workspace members to manually share pages via the “Add connections” menu. Public connections use the OAuth page picker, where users choose which pages to grant access to during the authorization flow.
Installation scope
Every public connection has an installation scope that controls which workspaces can install it. You pick the scope when you create the connection.| 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 |
How users authorize a public connection
When a user wants to use your public connection, they go through an OAuth authorization flow:The user visits the connection’s authorization URL. You’ll find this URL in the Configuration tab of your connection in the Creator dashboard.
Notion presents a prompt describing the connection’s capabilities — what it will be able to do in the user’s workspace.
After the user approves, Notion redirects them to your redirect URI with a temporary authorization code.
After a user authorizes a public connection, only that user can interact with the connection in their workspace. If multiple members in a workspace want to use the same public connection, each user needs to complete the authorization flow individually.
Creating a public connection
Navigate to the Creator dashboard.
Click Create new connection and fill in the required fields, including:
- Connection name and development 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)
- Connection capabilities (read content, update content, insert content, etc.)
After creation, visit the Configuration tab to retrieve your OAuth client ID and OAuth client secret. The client ID identifies your connection to Notion during the OAuth flow, and the client secret proves your connection 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 connection.
Preparing for users
Automate user onboarding after they install your connection.