> ## Documentation Index
> Fetch the complete documentation index at: https://docs.r28.ai/charter/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Charter works for any HTTP API, including the user's own. The packs are examples of the result, not the limit: an API with no pack is declared the same way, following https://raw.githubusercontent.com/r28ai/charter/main/docs/.mintlify/skills/declaring-charter-tools/SKILL.md.
> Charter is for agents that act in customers' accounts: every call is checked field by field before it's sent, the app says whose account each call is for, and the same declarations list what each tool can reach. https://docs.r28.ai/charter/llms.txt says what it is and lists every page.

# Register a public Notion integration

> The public integration your users connect, where each one picks the pages to share: the form, the redirect URI, its capabilities and its credentials, with a screenshot for each screen.

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](https://docs.r28.ai/charter/charter/auth/setup/notion.md) 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](https://www.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.](https://mintcdn.com/r28-ai-inc/xppyW240SSmPx0hQ/charter/images/setup/notion/01-integrations.webp?fit=max\&auto=format\&n=xppyW240SSmPx0hQ\&q=85\&s=982ab14ab1b3ffe3096ee99d0a8eb394)

**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.](https://mintcdn.com/r28-ai-inc/xppyW240SSmPx0hQ/charter/images/setup/notion/02-new-integration.webp?fit=max\&auto=format\&n=xppyW240SSmPx0hQ\&q=85\&s=b0f5442740db754d527ebef481f5589d)

* **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.](https://mintcdn.com/r28-ai-inc/xppyW240SSmPx0hQ/charter/images/setup/notion/03-redirect-uri.webp?fit=max\&auto=format\&n=xppyW240SSmPx0hQ\&q=85\&s=97414b008d722dfda4f9a95b371bfb97)

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.](https://mintcdn.com/r28-ai-inc/xppyW240SSmPx0hQ/charter/images/setup/notion/04-capabilities.webp?fit=max\&auto=format\&n=xppyW240SSmPx0hQ\&q=85\&s=38d6c53904103c20b974ea70610c1f2d)

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.](https://mintcdn.com/r28-ai-inc/xppyW240SSmPx0hQ/charter/images/setup/notion/05-client-secret.webp?fit=max\&auto=format\&n=xppyW240SSmPx0hQ\&q=85\&s=64de4e71df0cfffe99fc286fabd87f17)

```bash theme={null}
export NOTION_CLIENT_ID=2f8d1c4e-7b3a-4e19-9c60-5d2e8a7b1f03
export NOTION_CLIENT_SECRET=...
```

You don't need the **Authorization URL** shown below them.
[`flow.authorize()`](https://docs.r28.ai/charter/charter/reference/oauth#oauth2flow-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.](https://mintcdn.com/r28-ai-inc/xppyW240SSmPx0hQ/charter/images/setup/notion/08-consent.webp?fit=max\&auto=format\&n=xppyW240SSmPx0hQ\&q=85\&s=b904c80cd603c1b9b109c1f84dbd7518)

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](https://docs.r28.ai/charter/charter/auth/providers/notion.md). 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

> **“Missing or invalid redirect\_uri”**
>
> The flow sent a URI that isn't listed under **Redirect URIs**, character for
> character. A trailing slash is enough to break the match.

> **Every call succeeds and finds nothing**
>
> 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**.

> **403 on comment tools only**
>
> 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.

## Related

* [Notion OAuth](https://docs.r28.ai/charter/charter/auth/providers/notion.md) — the server constant and the per-user client
* [Getting the grant](https://docs.r28.ai/charter/charter/auth/oauth-flow.md) — the two routes, `state` and PKCE, inside your app
* [Notion](https://docs.r28.ai/charter/charter/packs/notion.md) — the pack, and how a database differs from the table inside it
* [Set up Notion](https://docs.r28.ai/charter/charter/auth/setup/notion.md) — your own workspace, with an internal integration


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.