Notion internal integrations

Connect a Notion internal integration using its secret. Its capabilities control the operations it can perform, and its page connections control the content it can access.

Prerequisites

You need a Notion workspace owner to create the integration. Internal integrations are a workspace-level feature — only workspace owners can access the integrations settings and create them.

Set up the integration

1. Create the internal integration

1. 1

   Open notion.so/profile/integrations (in Notion: Settings → Connections → Develop or manage connections) and create a new integration. Notion is renaming integrations to "connections" — newer workspaces see this at app.notion.com/developers/connections with a Create a new connection button.

2. 2

   Give it a name (e.g. sim-notion-bot), pick the workspace it belongs to, and make sure you are creating an internal integration (the default; newer UIs list it under Internal connections)

3. 3

   Under Capabilities, enable what your workflows need:

   • Read content — reading pages and blocks, querying and reading databases, search
   • Insert content — creating pages and databases, adding database rows, appending blocks
   • Update content — updating pages and blocks, deleting blocks
   • Comment capabilities — creating and listing comments
   • User capabilities — listing and reading workspace users (choose with or without email)

   Enable only what you use — a read-only reporting workflow needs just Read content.

4. 4

   Save, then copy the integration's secret from its settings page — depending on your workspace's UI it is labeled Internal Integration Secret or Installation access token (under the Configuration tab). Secrets issued since September 2024 start with ntn_; older secret_ tokens remain valid.

2. Connect pages and databases

A new internal integration has no page access. Connect each required top-level page or database; its child pages inherit access. You can also select content from the connection's Content access tab in Notion's Developer portal.

1. 1

   Open a page or database your workflows need in Notion

2. 2

   Click the ••• menu in the top-right, choose Connections (or Add connections), and select your integration

3. 3

   Repeat for each top-level page or database. Connecting a page also grants access to all of its sub-pages.

Add the internal integration to Sim

1. 1

   Open Integrations from your workspace sidebar

2. 2

   Search for "Notion" and open it, then click Add to Sim and choose Add integration secret

3. 3

   Paste the Internal integration secret, and optionally set a display name and description

4. 4

   Click Add integration secret. Sim verifies the secret by calling Notion's bot-user endpoint — if it fails, you'll see a specific error explaining what went wrong.

Use the credential in workflows

Add a Notion block to your workflow. In the credential dropdown, select the saved Notion internal integration. Configure the selected operation.

The block calls api.notion.com using the integration secret — the same API request paths as OAuth credentials. Available operations depend on the enabled capabilities and connected pages.

Troubleshooting and rotation

An internal connection acts as its own bot user. Its access comes from its capabilities and connected pages, and remains independent of the member who shared those pages. See Notion's internal connection permissions.

To rotate, refresh the token from Configuration, then select Reconnect on the saved credential in Sim's Integrations page and paste the new token. Plan for the old token to stop working; verify a page read after reconnecting.