All integrations have associated 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. To set your integration's capabilities see the Authorization guide.

Content capabilities

Content capabilities affect how an integration can interact with database objects, page objects, and block objects via the API. Additionally, these capabilities affect what information is exposed to an integration in API responses. To verify which capabilities are needed for an endpoint's desired behavior, please use the API references.

Read content

  • This capability gives the integration access to read existing content in a Notion workspace.
    For example, an integration with only this capability is able to call Retrieve a database , but not Update database.

Insert content

  • This capability gives the integration permission to create new content in a Notion workspace. This capability does not give the integration access to read full objects.
    For example an integration with only this capability is able to Create a page but is not able to update existing pages.

Update content

  • This capability gives the integration permission to update existing content in a Notion workspace.
    For example, an integration with only this capability is able to call the Update page endpoint, but is not able to create new pages.

It is possible for an integration to have any combination of these content capabilities.

User capabilities

Additionally, an integration can request 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 any information about the user, including name, profile images, or their email address.
  • User information without email addresses - user objects will include all information about a user, 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.

Capability Behaviors and Best Practices

An integration's capabilities will never supersede a user's. If a user looses edit access to a page where they have added an integration, that integration will now also only have read access, regardless of the capabilities the integration was created with.

For public integrations, users will need to re-authenticate with an integration if the capabilities are changed in the time since the user last authenticated with the integration.

To learn more about setting your integration's capabilities refer to the Authorization guide.

In general, you only want to request capabilities that your integration needs in order to function. The fewer capabilities you request, the more likely a workspace admin will be install your integration.

For example:

  • If your integration is solely bringing data into Notion (creating new pages, or adding blocks), your integration only needs insert content capabilities.
  • If your integration is reading data to export it out of Notion, your integration will only need read capabilities.
  • Or if your integration is only updating a property on a page or an existing block, your integration will only need update content capabilities.