When you connect third-party apps to your Notion workspace, each integration can access databases, pages, and blocks. Without limits, a single integration could consume all API rate allowances or expose more data than intended. This article explains how to set API integration capability limits in your Notion workspace to control what each integration can do and how much it can request.
Notion provides workspace-level settings to manage connected integrations. You can restrict an integration to specific pages, disable write access, or revoke its token entirely. The steps below cover how to configure these limits for existing and new integrations.
You will learn how to find the integrations manager, modify permissions, and apply the correct scope for each use case. The article also covers common mistakes that break an integration and how to avoid them.
Key Takeaways: Controlling Notion API Integration Access
- Settings & Members > My connected apps > Manage integrations: Lists every integration with its current permission scope.
- Integration capability toggles (Read content, Insert content, etc.): Enable or disable specific API actions such as reading databases or creating new blocks.
- Internal Integration Secrets page: Generate a new token with a restricted set of capabilities instead of using the default full-access token.
Understanding Notion API Integration Capabilities
Every Notion integration, whether public or internal, is assigned a set of capabilities when its token is created. These capabilities define what the integration can do through the Notion API. The main capability groups are:
- Read content — allows the integration to read pages, databases, blocks, and their properties.
- Insert content — allows the integration to create new pages, databases, and blocks.
- Update content — allows the integration to modify existing pages, databases, blocks, and properties.
- Delete content — allows the integration to remove pages, databases, and blocks.
Each integration also has a rate limit. Notion enforces a maximum of three requests per second per integration. If an integration exceeds this rate, Notion returns a 429 Too Many Requests error. Capability limits do not affect rate limits directly, but restricting capabilities can reduce the number of requests an integration makes, indirectly helping you stay under the rate ceiling.
Workspace owners and admins can also control which pages an integration can access. By default, an integration has access to all pages in the workspace. You can remove this access and grant it only to specific pages or databases. This is the most effective way to limit what data an integration can read or modify.
Steps to Set Up API Integration Capability Limits
Follow these steps to configure capability limits for an existing integration in your Notion workspace. The process applies to both internal integrations you created and public integrations you have connected from the Notion integrations directory.
- Open the Integrations Manager
Go to Settings & Members in the left sidebar. Under the Workspace section, click My connected apps. You will see a list of all integrations connected to your workspace. - Select the Integration to Modify
Find the integration you want to limit. Click its name to open the integration details panel. The panel shows the integration name, icon, and the permissions it currently has. - Adjust Capability Toggles
In the Capabilities section, you will see toggles for Read content, Insert content, Update content, and Delete content. Turn off any capability you want to revoke. For example, if the integration should only read data, disable Insert, Update, and Delete. Click Save changes. - Restrict Page Access
Below the capabilities, you will see Page access. By default it is set to All pages. Click Change and select Specific pages. A search box appears. Type the name of the page or database the integration should access. You can add multiple pages. Click Confirm. - Revoke the Integration Token if Needed
If you want to completely disable the integration, click Remove integration at the bottom of the panel. This revokes the token. The integration will receive a 401 Unauthorized error on its next API call. To re-enable it later, you must generate a new token and reconnect.
Creating a New Internal Integration with Limited Capabilities
If you are building a new integration from scratch, you can set its capabilities at creation time. This prevents the integration from ever having full access.
- Go to the Internal Integrations Page
Navigate to https://www.notion.so/my-integrations. Click New integration. - Name the Integration and Select Workspace
Give the integration a descriptive name. Choose the workspace where it will operate. Click Submit. - Configure Capabilities
On the integration detail page, scroll to Capabilities. You will see the same four toggles. Turn off any capability the integration does not need. For a read-only integration, disable Insert, Update, and Delete. - Generate the Token
Click Show token and copy the secret. This token now carries only the capabilities you enabled. Paste it into your application code. - Share the Integration with Specific Pages
In your Notion workspace, go to the page or database you want the integration to access. Click the three-dot menu in the top-right corner. Select Connections and find your new integration. Click Connect. The integration can now only interact with that page and its children.
Common Mistakes When Setting API Integration Limits
Integration Stops Working After Changing Capabilities
If you disable a capability that the integration relies on, it will fail on the next API call that requires that capability. For example, if you disable Insert content, the integration cannot create new database items. The API returns a 403 Forbidden error. To fix this, re-enable the missing capability in the integration details panel.
Integration Cannot Access a Page After Restricting Access
When you change page access from All pages to Specific pages, the integration loses access to every page not explicitly added. If the integration needs to read a parent page to traverse to a child page, you must add both the parent and the child. Add the pages one by one using the search box.
Rate Limit Errors After Restricting Capabilities
Restricting capabilities does not change the rate limit of three requests per second. If your integration still hits the rate limit, you must implement retry logic with exponential backoff in your application code. Notion does not provide a way to increase the rate limit for any integration.
Notion API Integration Capability Limits Compared
| Capability | Default (Full Access) | Read-Only | Custom Limited |
|---|---|---|---|
| Read content | Enabled | Enabled | Enabled or disabled |
| Insert content | Enabled | Disabled | Enabled or disabled |
| Update content | Enabled | Disabled | Enabled or disabled |
| Delete content | Enabled | Disabled | Enabled or disabled |
| Page access | All pages | Specific pages | Specific pages |
| Rate limit | 3 req/s | 3 req/s | 3 req/s |
You can now control what each Notion integration can read, write, update, or delete. Start by reviewing your existing integrations in Settings & Members > My connected apps and applying the strictest set of capabilities that still allow the integration to function. For new integrations, always generate the token with only the capabilities you need. The combination of capability toggles and page-level access is the most precise way to limit an integration without breaking it.