Connect with an internal integration
Connect Notion with an internal integration secret instead of signing in. The five capabilities it needs, sharing pages with it, and how to fix errors.
Signing in to Notion is the default way to connect it to Whalesync. An internal integration is an alternative if you prefer not to sign in, or are setting up a sync through the API or MCP server and need a credential to hand over.
An integration's secret differs from signing in in four ways:
- It does not expire.
- It reaches only the pages and databases you share with the integration.
- It can be pasted into the API or given to an agent. A sign-in has to happen in a browser.
- Changes in Notion reach Whalesync on the normal polling schedule. Instant updates through webhooks are only for connections that signed in.
Create the integration
Section titled “Create the integration”- Go to notion.so/profile/integrations and click New integration.
- Name it
Whalesync, choose the workspace you will sync, and set the type to Internal. - Save it, then turn on every capability listed below in the integration's settings.
- Copy the Internal Integration Secret. It starts with
ntn_, orsecret_on older integrations.
Capabilities
Section titled “Capabilities”All five are required.
| Capability | Why Whalesync needs it |
|---|---|
| Read content | Read your databases and pages. |
| Update content | Update pages and their properties during sync. |
| Insert content | Create pages, and create databases when you ask for them. |
| Read comments | Read comments on your pages. |
| Read user information including email addresses | Match person properties to people by email. |
Share pages with the integration
Section titled “Share pages with the integration”An integration sees nothing until a page or database is shared with it.
- In Notion, open each database you will sync, or a page that holds them.
- Open the ••• menu, choose Connections, and add
Whalesync.
Whalesync's base picker shows only what the integration can see. To let Whalesync create new databases, share at least one page for it to create them in.
One workspace per integration
Section titled “One workspace per integration”An integration belongs to one workspace, so a connection made with its secret syncs that workspace. Reauthorizing with a secret from an integration in another workspace is refused.
Paste the secret into Whalesync
Section titled “Paste the secret into Whalesync”- In the connect step, choose the link to use an internal integration secret instead of signing in.
- Paste the secret and click Authorize.
- Confirm the workspace.
A connection keeps its method. To switch between secret and sign-in, create a new connection.
Errors
Section titled “Errors”| Message | What to do |
|---|---|
| Notion did not accept this internal integration secret | The secret was copied wrong, refreshed, or the integration was deleted. Copy the current secret from the integration's settings. |
| This internal integration is missing a capability Whalesync needs | Turn on all five capabilities above in the integration's settings, then try again. |
| This internal integration belongs to a different Notion workspace | Use an integration created in the workspace this connection syncs. The message ends with that workspace's ID, in parentheses. |
Revoking the secret
Section titled “Revoking the secret”Deleting the integration, or refreshing its secret, stops every sync using it until you reconnect with a new secret.