# Connect Notion

Canonical URL: https://docs.fuse.init.inc/integrations/notion/setup

Configure a Notion public integration OAuth client and create a verified Init connection.



## Before you start [#before-you-start]

**Engine operator** creates one Notion public OAuth integration for the Init platform. **Connection admin/user** authorizes that integration and shares the Notion pages or databases Init should access.

You need:

* A Notion workspace with permission to create integrations (usually workspace owner).
* Ability for connection users to share pages with the integration after Connect.
* The engine public base URL for the OAuth redirect URI.

## Configure the provider [#configure-the-provider]

### One-time platform Notion integration (**Engine operator**) [#one-time-platform-notion-integration-engine-operator]

1. Open [Notion’s My integrations](https://www.notion.so/my-integrations) and create a **Public** integration (OAuth).

2. Set the redirect URI to:

   `{FUSE_PUBLIC_URL}/v1/oauth/notion/callback`

3. Configure the integration capabilities to match the Init actions you expose (read content, insert content, and so on). Do not enable unused capabilities.

4. Copy the OAuth client ID and client secret into the Fuse environment as `NOTION_CLIENT_ID` and `NOTION_CLIENT_SECRET`. Never commit these values.

### Per-workspace authorization (**Connection admin/user**) [#per-workspace-authorization-connection-adminuser]

Customers authorize the public integration via Connect, then explicitly share Notion pages or databases with the integration bot.

## Connect to Init [#connect-to-init]

1. **Connection admin/user** starts a Notion Connect session.
2. Complete Notion OAuth (`owner=user`) and select the workspace.
3. In Notion, share the specific pages or databases the bot should read or update.
4. Init stores the workspace bot token from the OAuth exchange. No customer credential fields are typed into Connect.

If capabilities or requested access change, reconnect and re-share content as needed.

## Permissions [#permissions]

Notion access is capability-based on the integration plus page-level sharing. The generated action list describes what Init can call; the bot only sees pages and databases shared with it.

Workspace owners control whether members may install public integrations. Content not shared with the integration remains inaccessible even after a successful OAuth grant.

## Verify the connection [#verify-the-connection]

1. Confirm Connect completes and Init shows an active Notion connection for the expected workspace.
2. Share a non-sensitive page with the integration, then run a safe search or page read.
3. Success looks like Notion returning the shared page without `unauthorized` / object-not-found errors caused by missing shares.

## Rotate or revoke access [#rotate-or-revoke-access]

* **Rotate platform secrets (Engine operator):** regenerate the Notion client secret, update `NOTION_CLIENT_SECRET`, then retire the previous secret.
* **Revoke customer access (Connection admin/user):** remove the integration from the Notion workspace or unshare pages, then delete or reconnect the Init connection.
* After changing integration capabilities, reconnect so Notion issues a grant that matches the new capabilities.

## Troubleshooting [#troubleshooting]

| Symptom                       | What to check                                                                                  |
| ----------------------------- | ---------------------------------------------------------------------------------------------- |
| Redirect URI mismatch         | Must equal `{FUSE_PUBLIC_URL}/v1/oauth/notion/callback`.                                       |
| OAuth succeeds but reads fail | Page or database was not shared with the integration bot.                                      |
| Wrong workspace               | Re-run Connect and select the intended Notion workspace.                                       |
| Capability errors             | Platform integration capabilities must cover the Init actions in use; reconnect after changes. |
| Fuse OAuth cannot start       | Confirm `NOTION_CLIENT_ID` and `NOTION_CLIENT_SECRET` on Fuse.                                 |