Scopes - Notion Docs

When you create an organization bot token, you assign scopes that control which resources the token can access and which actions it can take. Each scope combines a resource and a capability, such as legal-hold:read.

The user and permission-group scopes are available only to eligible Enterprise organizations. If these scopes don’t appear in the organization console, contact your Notion representative.

Scope resources

Scope resource	Controls access to
`legal-hold`	Legal hold data and members
`managed-user-session`	Managed users’ active sessions
`mcp-client-connection`	Members’ MCP client connections
`permission-group`	Workspace permission groups and direct memberships
`personal-access-token`	Personal access tokens in the organization’s workspaces
`user`	Workspace people and bots
`workflows`	Custom-agent inventory and governance
`workspace`	Workspace data and settings

This table may not include every scope. Each endpoint’s reference lists the exact scope it requires.

Scope capabilities

Scope capability	Allows the token to
`read`	View a resource
`write`	Modify a resource
`write-high-impact`	Make sensitive changes, such as revoking credentials or access
`export`	Export a resource

Scope capabilities are independent. For example, permission-group:write does not grant permission-group:read. Assign both scopes when a connection must inspect groups or memberships before changing them.