Notion API Internal Integration Permission Inheritance for Guest-Shared Pages

Answer

No – an internal integration’s access does not override or depend on the permission level set for external Guests. The integration can act on a page only if it has been explicitly shared to that page and its own capability flags (Read Content, Update Content, etc.) are enabled.

Likely explanation

When a page is shared with a Guest, Notion stores the Guest’s role in the page’s share list. Internal integrations are treated as a separate share entry; they do not inherit the Guest’s role, nor does the Guest’s role limit the integration’s actions.

Confirmed facts (from Notion’s documentation)

• Internal integrations only access pages they have been explicitly added to or that satisfy workspace‑level capabilities.
• To give an integration access to a guest‑shared page you must call the share endpoint and add the integration as a recipient with the desired role (e.g., editor).
• The integration must have the corresponding capability (Read Content, Update Content, Insert Content) enabled in its settings before the share call will succeed.
• After sharing, the integration can read or modify the page according to its enabled capabilities, independent of the Guest’s permission level.

Steps to grant the integration access to a guest‑shared page

1. In the Notion developer portal, enable the required capabilities for your integration (e.g., Read Content and Update Content).
2. Obtain the page ID and your integration’s internal integration ID (the bot token’s integration_id).
3. Call the share endpoint:

POST https://api.notion.com/v1/pages/{PAGE_ID}/share
Authorization: Bearer {YOUR_INTEGRATION_SECRET}
Notion-Version: 2022-06-28
Content-Type: application/json

{
  "type": "integration",
  "integration_id": "{YOUR_INTEGRATION_ID}",
  "role": "editor"
}

1. Verify the response (200 OK) and that the returned share list includes the integration.
2. Optionally, test access with a read request:

GET https://api.notion.com/v1/pages/{PAGE_ID}
Authorization: Bearer {YOUR_INTEGRATION_SECRET}
Notion-Version: 2022-06-28

If the integration lacks the Update Content capability, the share request will succeed but subsequent update calls will return 403 Forbidden.