Notion internal integrations let your workflows authenticate to Notion as a workspace-owned bot user instead of through a person's OAuth login. The integration has its own secret, its own capabilities, and its own explicit list of pages and databases it can reach — all managed from the workspace's integration settings.
This is the recommended way to use Notion in production workflows: the secret doesn't depend on any employee's account, its capabilities are explicit, and access is granted page by page rather than inheriting one person's entire sidebar.
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.
Setting Up the Integration
1. Create the Internal Integration
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.
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)
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.
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.
The secret is bearer credentials for everything the integration is connected to. Treat it like a password — do not commit it to source control or share it publicly. Sim encrypts the secret at rest.
2. Connect the Integration to Pages and Databases
This step is the one everyone misses — and without it, the integration can read nothing. A brand-new integration has API access but zero page access; every page or database your workflows touch must be explicitly connected.
Open a page or database your workflows need in Notion
Click the ••• menu in the top-right, choose Connections (or Add connections), and select your integration
Repeat for each top-level page or database. Connecting a page also grants access to all of its sub-pages.
A valid secret with no page connections validates fine in Sim but returns 404 object_not_found on every real call. If a Notion block reports that a page or database wasn't found — and you're sure the ID is right — the page isn't connected to the integration.
Adding the Service Account to Sim
Open your workspace Settings and go to the Integrations tab
Search for "Notion Service Account" and click it, then click Add to Sim and choose Add integration secret
Paste the Internal integration secret, and optionally set a display name and description
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.
Using the Service Account in Workflows
Add a Notion block to your workflow. In the credential dropdown, your Notion service account appears alongside any OAuth credentials. Select it and configure the block as you normally would.
The block calls api.notion.com using the integration secret — exactly the same requests as the OAuth flow, so every Notion tool works unchanged, limited to the capabilities you enabled and the pages you connected.