# Notion internal integrations (/integrations/notion-service-account)

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 \[#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 \[#setting-up-the-integration]

### 1. Create the internal integration \[#1-create-the-internal-integration]

Open [notion.so/profile/integrations](https://www.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.

Warning:

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 pages and databases \[#2-connect-the-integration-to-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.

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.

Warning:

The bot-user check can succeed without page access. A content request can then return `404 object_not_found`; check both the identifier and the page connection.

## Add the internal integration to Sim \[#adding-the-internal-integration-to-sim]

Open **Integrations** from your workspace sidebar

Search for "Notion" and open 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.

## Use the credential in workflows \[#using-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 \[#troubleshooting-and-rotation]

| Error | What to check |
| - | - |
| `404 object_not_found` | Check the page or database ID and connect that content to the internal integration. A successful bot-user check does not prove page access. |
| `403 restricted_resource` | Enable the operation's content, comment, or user capability in the connection settings. |
| Invalid secret | Copy the current token from **Configuration**. Sim treats tokens as opaque strings and accepts the legacy `secret_` and newer `ntn_` prefixes. |

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](https://developers.notion.com/guides/get-started/internal-connections).

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.