Notion Connection and Authentication Intake: first-party evidence
Reviewed: 2026-09-12
Notion's public documentation establishes the current product and API contract. The selected connection's type, workspace binding, capabilities, explicitly shared content, selected tested API version, and observed responses remain execution evidence for that environment.
- Connection models and access
- Authorization flows
- Authentication
- Connection capabilities
- Secure API tokens
Current contract notes
- At review time, the current REST contract is
2026-03-11; send a testedNotion-Versionon REST calls and use a compatible SDK. - The modern model separates database containers from data sources. Query and schema operations use a data-source ID; search returns pages and data sources.
- The current contract uses a position object for block placement,
in_trashfor REST trash state, andmeeting_notesfor the renamed block type. - Request limits can change. Handle HTTP 429, honor
Retry-After, bound retries, paginate completely, and tolerate additive response fields. - Skill invocation never grants permission to access credentials or workspace data, expand capabilities or sharing, write content, subscribe webhooks, transfer files, deploy, spend money, or delete resources.
Evidence rules
- Recheck these pages at execution time and record the selected API version, SDK version, connection alias, workspace alias, source revision, and observation date.
- Keep internal connections, public OAuth connections, personal access tokens, connection webhooks, database-automation webhooks, MCP, Workers, and Admin APIs as distinct contracts.
- When first-party documentation and observed behavior differ, fail closed, preserve redacted request evidence, and resolve the discrepancy before mutation.