V2
认证与权限
了解 Bearer Token、可用 scope、公共路由和常见鉴权失败原因。
认证与权限
V2 API 使用 Bearer Token 认证。所有需要鉴权的请求都要在请求头里带上：
Authorization: Bearer <token>注意这里的格式是严格的 Bearer <token>，不是 query 参数，也不是 body 字段。格式不正确的请求会直接返回认证错误。
公共路由与受保护路由
除公开元数据接口外，其他 /v2/* 路由都会要求先完成认证。对外公开、无需 token 的只有这两个路由：
| 路由 | 说明 |
|---|---|
GET /v2/openapi.json | 返回当前 OpenAPI 文档 |
GET /v2/openapi/meta | 返回 OpenAPI 元数据，如 etag、生成时间和路径数量 |
除这两个路由之外，其他所有 /v2/* 请求都会先做认证检查。这意味着：
- 没有 token 的请求会返回
401 - token 无效、过期、工作区不存在或被禁用时会返回
401 - 免费计划会返回
403 - scope 不足时会返回
403
Token 类型
Integration token 和 OAuth token 使用同一种传递方式，客户端不需要用不同的 header 区分它们。二者都写成：
Authorization: Bearer <token>FlowUs 会识别 token 类型，但这不会改变请求格式。
免费计划限制
如果 token 所属空间是免费计划，V2 API 会直接拒绝访问。个人免费版和团队免费版都会被判定为不可用，并返回 403。
请求即使已经带上合法 token，也仍然可能因为空间计划类型而失败。
可用 scope
V2 API 支持的 scope 如下：
| Scope | 说明 |
|---|---|
pages.read | 读取页面相关资源 |
pages.write | 创建、更新、删除页面或页面内容 |
blocks.read | 读取 block 或 block children |
blocks.write | 修改 block 或追加 block children |
databases.read | 读取数据库或执行数据库查询 |
databases.write | 创建、更新、删除数据库 |
users.read | 读取指定用户信息 |
users.email.read | 读取用户邮箱相关信息 |
search.read | 执行标准搜索或语义搜索 |
能力到 scope 的对应关系
FlowUs 会根据 token 对应的集成能力生成对外可见的 scope 列表。映射关系如下：
| capability | 映射到的 scopes |
|---|---|
readContent | pages.read、blocks.read、databases.read、search.read |
insertContent 或 updateContent | pages.write、blocks.write、databases.write |
readUserWithoutEmail | users.read |
readUserWithEmail | users.email.read |
映射结果会去重，所以同一个 scope 不会重复返回。
常见 401 / 403
- 先确认请求头是不是
Authorization: Bearer <token>，有没有漏掉Bearer或者多写空格。 - 再确认 token 是否有效，是否已经过期，是否确实属于当前空间。
- 如果返回的是
403，先看是不是免费计划。 - 如果不是免费计划，再核对当前路由是否需要额外 scope。
GET /v2/users/me本身只要求有效 token，不额外要求某个读写 scope，所以它通常适合用来先验证 token 是否可用；如果这里都失败，问题一般在认证层，而不是 scope 层。