I’m building a simple app that connects to Notion using their API. After a user goes through the OAuth flow, they can pick which pages or databases they want to share with my app.
The problem is I can’t figure out how to get the list of what they actually granted access to. I need to know which specific pages and databases are available so my app can work with them properly.
Is there an endpoint or method in the Notion API that returns the permissions scope after OAuth completes? I’ve looked through the docs but maybe I’m missing something obvious.
Any help would be great since I’m stuck on this part of the integration.
No single endpoint lists your granted permissions after OAuth, but here’s how I handle it. Right after the OAuth callback, I store the access token and run discovery calls. I hit the search endpoint with an empty query to see what’s accessible, plus make separate calls to enumerate databases and pages. Here’s the thing - Notion’s OAuth isn’t blanket access. Users pick individual resources during auth, so you can’t rely on some permissions list. You’ve got to test what you can actually reach. I built a background job that runs these discovery calls, caches results, and refreshes periodically since permissions change. The search endpoint pagination is a pain but works reliably once you get it right.
have you tried usin the search endpoint? just send a search req with an empty query, and it should show all pages and dbs your app can access. works for me most of the time!
yeah, oauth permissions in notion are a mess. i just hit whatever endpoints i need and catch the 403s. if it blocks you, you know you can’t access that page or database. not pretty, but it works and beats doing discovery calls first.
OAuth responses don’t give you a direct list of what you can access, but you can figure it out with a few API calls. After OAuth completes, hit /v1/users/me for basic user info, then use /v1/search with different filters to see what’s available. For databases, try /v1/databases with pagination. I’ve found that running these discovery calls right after OAuth gives you the full picture of what the user shared. Just remember Notion’s permissions are pretty granular - you might be able to read some pages but not write to them, depending on what the user picked during auth.
The Problem: You’re building a Notion integration and need to determine which pages and databases a user has granted your app access to after the OAuth flow. The Notion API doesn’t provide a single endpoint to list all granted permissions.
Understanding the “Why” (The Root Cause):
Notion’s OAuth 2.0 flow grants access to specific resources (pages and databases) selected by the user, not blanket access to their entire Notion workspace. Therefore, there isn’t a dedicated endpoint returning a comprehensive permission list. You must proactively discover the accessible resources using the API.
Step-by-Step Guide:
Automate Post-OAuth Resource Discovery: After a successful OAuth flow and you have obtained the user’s access token, immediately trigger a background process or function to perform discovery calls. This approach prevents blocking the main user flow while comprehensively gathering information on accessible resources. Consider using a task queue or background job service to handle this asynchronously.
Fetch User Information (Optional but Recommended): Make a call to /v1/users/me using the access token. This provides context about the user and their workspace ID, which can be helpful for debugging and filtering subsequent calls.
Use the Notion Search Endpoint /v1/search: The search endpoint, while not ideal for large workspaces due to pagination, offers a relatively simple way to discover accessible pages and databases. Send a POST request to /v1/search with an empty query ({} as the request body). This returns a list of pages and databases the user has granted your app access to. Implement proper pagination to handle potentially large result sets. This approach requires handling the next_cursor to retrieve all pages.
Iterative Database and Page Enumeration (More Efficient Alternative): For larger workspaces, performing iterative database and page enumeration is more efficient than relying solely on the search endpoint. First, list all databases the user has access to using /v1/databases (with pagination). Then, for each database, retrieve its pages (with pagination). This direct approach avoids the overhead of the broad search.
Data Storage and Caching: Store the results of your discovery calls efficiently. A caching mechanism (like Redis or Memcached) is highly recommended to reduce API calls and improve performance for subsequent requests. Refresh your cache periodically, considering the likelihood of permission changes.
Error Handling: Implement robust error handling to gracefully manage API request failures (rate limits, network issues, permission denials). Consider using exponential backoff to avoid overwhelming the Notion API.
Technology Choice: The choice of technology for implementing background jobs and data storage depends on your application’s requirements. While the example mentions Latenode, other alternatives like AWS Lambda, Google Cloud Functions, or self-hosted solutions may also be suitable.
Common Pitfalls & What to Check Next:
Rate Limits: Notion’s API has rate limits. Implement proper error handling and exponential backoff strategies to avoid exceeding these limits.
Pagination: Correctly handle pagination in all API calls. Always check for has_more and next_cursor in the responses.
Access Token Validity: Ensure your access token is valid and hasn’t expired. Implement appropriate token refresh mechanisms.
Insufficient Permissions: If a resource isn’t returned in the discovery calls, the user might not have granted your app access to it.
Still running into issues? Share your (sanitized) config files, the exact command you ran, and any other relevant details. The community is here to help!
Understanding the “Why” (The Root Cause):
Step-by-Step Guide:
Common Pitfalls & What to Check Next:
Still running into issues? Share your (sanitized) config files, the exact command you ran, and any other relevant details. The community is here to help!