V2
Scope 清单
查看 V2 scopes 及其与接口权限的映射关系。
Scope 清单
适用范围
本页只列出 V2 API 对外可见的 scope，以及它们与接口权限的对应关系。授权流程本身和 token 生命周期放到入门页说明。
核心定义
| Scope | 说明 |
|---|---|
pages.read | 读取页面和页面属性。 |
pages.write | 创建、更新和删除页面。 |
blocks.read | 读取块及其子块。 |
blocks.write | 创建、更新和删除块。 |
databases.read | 读取数据库结构和查询数据。 |
databases.write | 创建、更新和删除数据库。 |
users.read | 读取用户基础信息。 |
users.email.read | 读取用户邮箱。 |
search.read | 使用搜索能力。 |
字段说明或规则
scope 含义
users.email.read是附加权限，不会自动包含在users.read中- 多个 scope 同时存在时，调用方需要按接口要求同时满足
- scope 不足时，通常返回
403 forbidden
接口 → scope 映射
| 接口 | 所需 scope |
|---|---|
GET /v2/users/:user_id | users.read |
GET /v2/pages/:page_id | pages.read |
GET /v2/pages/:page_id/properties/:property_id | pages.read |
GET /v2/pages/:page_id/content/markdown | pages.read + blocks.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 |
POST /v2/search | search.read |
POST /v2/search/semantic | search.read |
POST /v2/files/upload-url | pages.write |
GET /v2/openapi.json 和 GET /v2/openapi/meta 是公开路由，不参与 scope 校验。
常见注意事项
- 先确认 token 类型和授权范围，再判断接口是否可调用。
users.read只保证能读到基础信息，邮箱是否返回还要看users.email.read。