Scope Reference

Review V2 scopes and how endpoint permissions map to them.

Scopes control what a token can do. The token must have every scope required by an endpoint.

Scopes

Scope	Description
`pages.read`	Read page metadata and properties.
`pages.write`	Create, update, delete, and upload files for page workflows.
`blocks.read`	Read blocks and block children.
`blocks.write`	Append, update, and delete blocks.
`databases.read`	Read databases and query records.
`databases.write`	Create, update, and delete databases.
`users.read`	Read user profiles.
`users.email.read`	Return user email addresses in `person.email`.
`search.read`	Run keyword and semantic search.

Endpoint	Scope
`GET /v2/users/me`	No additional scope.
`GET /v2/users/:user_id`	`users.read`; `users.email.read` controls email visibility.
`POST /v2/search`	`search.read`
`POST /v2/search/semantic`	`search.read`
`GET /v2/pages/:page_id`	`pages.read`
`GET /v2/pages/:page_id/properties/:property_id`	`pages.read`
`POST /v2/pages`	`pages.write`
`PATCH /v2/pages/:page_id`	`pages.write`
`DELETE /v2/pages/:page_id`	`pages.write`
`GET /v2/blocks/:block_id`	`blocks.read`
`GET /v2/blocks/:block_id/children`	`blocks.read`
`PATCH /v2/blocks/:block_id/children`	`blocks.write`
`PATCH /v2/blocks/:block_id`	`blocks.write`
`DELETE /v2/blocks/:block_id`	`blocks.write`
`GET /v2/databases/:database_id`	`databases.read`
`POST /v2/databases/:database_id/query`	`databases.read`
`POST /v2/databases`	`databases.write`
`PATCH /v2/databases/:database_id`	`databases.write`
`DELETE /v2/databases/:database_id`	`databases.write`
`GET /v2/pages/:page_id/content/markdown`	`pages.read` + `blocks.read`
`PUT /v2/pages/:page_id/content/markdown`	`pages.write` + `blocks.write`
`POST /v2/files/upload-url`	`pages.write`