Changelog
View my integrations
Back to All

Integrations support granular capabilities

about 3 years ago by Kiran Pandit

Both public and internal integrations now support having more granular capabilities, which enforce what an integration can do and see in a Notion workspace. These capabilities when put together enforce which API endpoints an integration can call, and what content and user related information they are able to see. For further information on capabilities and best practices, see the capabilities reference.

Content capabilities

Integrations can have any combination of read content, insert content, or update content capabilities.

  • The read content capability gives the integration access to read existing content in a Notion workspace.
  • The insert content capability gives the integration permission to create new content in a Notion workspace.
  • The update content capability gives the integration permission to update existing content in a Notion workspace.

User capabilities

Integrations have different levels of user capabilities, which affect how user objects are returned from the Notion API:

  • No user information - the integration will not be able to request any information about users. User objects will not include information about the user, including name, profile images, or their email address.
  • User information without email addresses - user objects will include other information about the user, including their name or profile images, but omit the email address.
  • User information with email addresses - user objects will include all information about the user, including name, profile images, and their email address.

Limitations

An installed integration can never capabilities will never supersede the capabilities of the user who owns the integration. For example, an integration cannot insert or update on a page if the owner has read-only access.

Existing integrations

All existing integrations will continue to have the same functionality as before. Any integrations created before December 15, 2021 automatically will have all content capabilities, and user capabilities that give access to user information including email addresses.

Updating integrations

Update the capabilities on an existing integration through https://www.notion.so/my-integrations. After updating a public integration's capabilities, users will need to re-authenticate with the integration to apply the new capabilities to their installation. After re-authenticating a public integration with changed capabilities, or updating an internal integration with changed capabilities, the new capabilities will apply to all pages already shared with the integration. For more information on setting capabilities see the Authorization guide.