Skip to main content

​
What is an internal integration?

An internal integration is scoped to a single Notion workspace. Only members of that workspace can use it. Internal integrations are ideal for building custom automations and workflows — things like syncing data from external tools, sending notifications when pages change, or powering internal dashboards. Internal integrations use a static API token for authentication. There’s no OAuth flow to implement — you get a token immediately when you create the integration, and you use that same token for every API request. In this guide, you’ll learn:
  • How internal integration permissions work (and how they differ from public integrations)
  • How to create an internal integration and share pages with it
  • How to authenticate API requests using your integration token

​
How permissions work

An internal integration operates as its own bot user. It is not tied to any specific workspace member. This means:
  • Permissions belong to the integration, not to a person. When a page is shared with the integration, the integration itself has access — regardless of which workspace member shared it.
  • Access is inherited. Sharing a parent page with the integration grants access to all of its child pages as well.
  • Access persists independently of users. If the user who shared a page leaves the workspace, the integration retains access to that page.
  • Any Workspace Owner can see the integration. All internal integrations are visible in the Creator dashboard to every Workspace Owner in the workspace, including integrations created by others.
This is one of the biggest differences from public integrations, where the integration acts on behalf of the individual user who authorized it.

​
Creating an internal integration

You must be a Workspace Owner to create an integration.
1
Navigate to the Creator dashboard.
2
In the Build section of the sidebar, select Internal integrations.
3
Click Create a new integration and fill in the integration name and associated workspace.
4
After creation, visit the Configuration tab to retrieve your API token (the “Internal Integration Secret”).
You can also configure the integration’s capabilities — such as whether it can read content, update content, insert content, or read user information — from the Configuration tab.

​
Granting page access

Before your integration can access any data, it must be explicitly granted access to pages or databases. There are two ways to do this.

​
From the Creator dashboard

The integration owner can manage access directly from the Content access tab in the Creator dashboard. This is the quickest way to get started after creating an integration.
1
Open your integration in the Creator dashboard.
2
Click the Content access tab.
3
Click Edit access, then select the pages and databases you want the integration to access.

​
From the Notion UI

Workspace members can also share individual pages with the integration from within Notion.
1
Open a Notion page you want the integration to access.
2
Click the ••• menu in the top-right corner of the page.
3
Select Connections, then click + Add connection.
4
Search for your integration and select it.
5
Confirm the integration can access the page and all of its child pages.
Your integration needs page access to make API requestsA newly created integration has no page access by default. If you skip this step, any API request will return an error. Use the Content access tab or Add connections menu to grant access before making requests.

​
Authentication

Internal integrations authenticate every API request using the API token retrieved from the Configuration tab. Include the token in the Authorization header: 
GET /v1/pages/b55c9c91-384d-452b-81db-d1ef79372b75 HTTP/1.1
Authorization: Bearer {INTEGRATION_TOKEN}
If you’re using the Notion SDK for JavaScript, the token is set once when initializing the client: 
const { Client } = require("@notionhq/client")

const notion = new Client({
	auth: process.env.NOTION_TOKEN,
})
Keep your token secret. Never store the token in source code or commit it to version control. Use environment variables or a secret manager instead. If your token is accidentally exposed, you can refresh it from the integration’s Configuration tab.Learn more: Best practices for handling API keys
For the full details on internal integration authentication, see the Authorization guide.

​
Next steps

Getting started

Build your first integration with a hands-on tutorial.

API reference

Explore all available endpoints.