调用平台能力
应用拿到的 token 代表谁、权限怎么算;能申请哪些 scope;平台现在能提供什么(能用、即将上线、还没有、不做)。
调用平台能力
token
- 只有个人 token:代表正在用应用的那个人。没有应用身份 token,也没有组织级 token。
- 有效权限 = 已批准的 scope ∩ 这个人本身的权限。例如应用批了
work:project:write,没有该权限的成员调用照样 403。 - access token 15 分钟。过期后应用自己再跳一次授权端点(用户已登录 Workspace 时无感),外壳不参与。嵌入时改为重新向宿主要授权码,见登录「嵌入时登录」。
- 默认不发 refresh token。用户不在时也要运行(定时任务、夜间同步),manifest 里申请
offline_access,审批通过后才发(30 天,每次刷新轮换)。 - 用户标识是
member_id(=sub):同一组织内同一个人稳定。应用自己维护账号和映射,建议按(issuer, org_id, member_id)绑定(同一个人在不同组织是不同的member_id,绑定边界见已有系统接入)。 - token 响应 / id_token 里的邮箱要申请
org:me.email:read(GET /api/v1/me不受它控制)。邮箱不能当绑定键。 - Agent 和用户平级,调 Workspace 用 Agent 自己的凭据,不走应用授权链路。Agent 要回调你的应用有两种做法:平台的 Agent 应用令牌 + 主人授权(推荐,见Agent 调用应用),或由应用自己给 Agent 发 API key。
scope 列表见下面的「scope(权限)」。
scope(权限)
- 和个人 API Key(PAT)共用同一份 scope 目录,命名
域:资源:动作。提交页的 scope 列表读目录(GET /api/v1/app-scopes)。 - 目录里的 scope 对应用开放,只有下面两类不能申请:
apps:*应用管理 scope:其中只有apps:badge:write可以申请(用法见下文「应用角标」),其余都不能。- 伞形 scope(
api、read_api):不能申请,必须逐项勾选。
org:me:read由服务端自动补上,manifest 里不写也会有。- 级别:每个 scope 的敏感级别,L0 普通、L1 敏感、L2 高度敏感。只在审批和安装时提示:提交和审批卡显示这个应用申请的最高级别,安装时最高是 L2 会出红色警告。级别不影响权限,token 实际能做的仍是「批准的 scope ∩ 这个人本身的权限」。例:
org:me:read是 L0;org:member:read、发消息是 L1;读消息内容、读知识库是 L2。
| 分类 | scope | 说明 | 覆盖 | 级别 |
|---|---|---|---|---|
| 本人 | org:me:read |
本人基础信息(自动带上) | GET /api/v1/me | L0 |
| 通讯录 | org:member:read |
成员列表、详情 | GET /api/v1/members | L1 |
| 项目与任务 | work:project:read |
查看项目 | GET /api/v1/projects | L0 |
| 项目与任务 | work:project:write |
创建 / 推进项目 | POST /api/v1/projects | L1 |
| 项目与任务 | work:issue:read |
查看 Issue | GET /api/v1/projects/{project_id}/issues | L0 |
| 项目与任务 | work:issue:write |
创建 / 推进 Issue | POST /api/v1/projects/{project_id}/issues | L1 |
| 项目与任务 | work:task:read |
查看 Task | GET /api/v1/tasks | L0 |
| 项目与任务 | work:task:write |
创建 / 推进 Task | POST /api/v1/projects/{project_id}/issues/{issue_id}/tasks | L1 |
| 会话与消息 | messages:conversation:read |
会话列表、详情 | GET /api/v1/conversations | L1 |
| 会话与消息 | messages:message:read |
读取消息 | GET /api/v1/conversations/{id}/messages | L2 |
| 会话与消息 | messages:message:send |
以本人身份发消息 | POST /api/v1/conversations/{id}/messages | L1 |
| 知识库 | kb:space:read |
查看知识库 | GET /api/v1/kbs | L2 |
| 知识库 | kb:page:read |
查看知识库页面 | GET /api/v1/pages/{page_id} | L2 |
| 应用专用 | offline_access |
用户不在时以其身份运行(签发 refresh token) | token 响应里的 refresh_token | L1 |
| 应用专用 | org:me.email:read |
换 token 时返回邮箱 | token 响应 user.email 与 id_token email |
L1 |
| 应用专用 | apps:badge:write |
给本组织成员设应用角标 | PUT /api/v1/app-badges | L1 |
上表是常用项,完整列表以目录(开发文档抽屉的「scope 列表」)为准。
API 参考即将公开。本期应用接口主要用于登录和身份(见登录「用 /api/v1/me 确认身份和成员资格」)。
有效权限怎么算、token 怎么发,见上面的「token」。
能力清单
每项写明现在能不能用。用法和细节看各页对应的那一节,或 Chat SDK 文档。
- 能用:已上线(openmax.com)。
- 即将上线:还不能用,近期上线。
- 平台还没有:文档写明延后,没说做不做。
- 平台不做:平台明确列为本期不做。
应用形态与托管
| 能力 | 现在能不能用 | 详见 |
|---|---|---|
| 页面应用 · 带后端 | 能用 | 「应用类型」 |
| 纯前端应用(PKCE 公开客户端) | 平台还没有(会被拒收) | 「应用类型」「不做的事」 |
| 平台托管应用后端 | 平台还没有(后端自己部署) | 「不做的事」 |
打开与嵌入
| 能力 | 现在能不能用 | 详见 |
|---|---|---|
| 嵌入打开 / 新标签打开、多个入口 | 能用 | 「manifest」「打开方式与地址」 |
| 嵌入打不开时的新标签兜底 | 能用 | 「打开方式与地址」 |
| 入口地址带主题、语言参数,切换时推送 | 能用 | 「入口地址上的参数」 |
| 路由同步(openmax:location) | 能用 | 「路由同步」 |
应用请求打开会话(navigate,openChat({memberId})) |
即将上线 | 「应用请求打开会话」 |
| 宿主驱动应用导航、iframe 尺寸协商、query / hash 同步 | 平台不做(本期不做,未排期) | 「不做的事」 |
| 通用 postMessage 桥 | 平台还没有(延后) | 「不做的事」 |
| 宿主能力调用 | 平台还没有 | 「不做的事」 |
应用角标(apps:badge:write) |
能用 | 「scope」「应用角标」 |
| @openmaxai/app-sdk(协议的封装库) | 平台还没有(没发 npm,照协议自己实现) | 「入口地址上的参数」 |
身份与登录
| 能力 | 现在能不能用 | 详见 |
|---|---|---|
| 跳转登录:OAuth 2.0 授权码 + PKCE + id_token | 能用 | 「登录」 |
| refresh_token(offline_access) | 能用 | 「token 端点与令牌」 |
| 嵌入登录 requestAuthCode | 能用 | 「嵌入时登录」 |
| 宿主提示没接 requestAuthCode 的应用改用新标签 | 平台不做(不要依赖宿主提示;WebKit 上会白屏,所以嵌入必须接 requestAuthCode) | 「嵌入时登录」 |
| 统一 SSO(同步登录态、退出通知) | 平台还没有 | 「会话有效期」「不做的事」 |
| 应用身份 token / 组织级 token | 平台不做(本期不做;替代做法见) | 「token」「不做的事」 |
| Agent 打开应用 | 平台还没有 | 「应用类型」 |
| Agent 应用令牌 + 主人授权 | 能用(预览:请求和响应格式还没公开) | Agent 调用应用 |
权限
| 能力 | 现在能不能用 | 详见 |
|---|---|---|
| scope 目录(与个人 API Key 共用) | 能用 | 「scope」 |
| 安装审批、新版本审批(成员提交的每个新版本都要一位管理员审批) | 能用 | 「提交、审批、安装」「发新版本」 |
| 停用后 token 失效 | 能用(平台不通知应用) | 「安装、停用、卸载」 |
| 逐人同意(per-user consent) | 平台还没有 | 「安装、停用、卸载」 |
| 按动作收窄的授权、高风险操作二次确认 | 平台还没有(应用自己做) | 提交审批与安装「权限与审计」 |
聊天(Chat SDK)
| 能力 | 现在能不能用 | 详见 |
|---|---|---|
| @openmaxai/chat-sdk 等四个包 3.0.0-beta.5 | 能用(beta,接口未冻结;锁精确版本) | Chat SDK 文档 |
| 会话列表、消息线程、分栏布局、交互卡片 | 能用 | Chat SDK 文档 |
| Agent 执行过程只读进度 | 能用(实验性) | Chat SDK 文档 |
点头像开私聊(openConversation({ memberId })) |
能用 | Chat SDK 文档 |
| 私聊带上下文(上下文子会话) | 即将上线 | Chat SDK 文档 |
| Agent 运行(可停止、运行列表)、审批卡 | 规划中(无排期) | 规划中,暂无公开文档 |
| 凭据:个人 API Key 放服务端换短期令牌 | 能用(文档唯一写明的路) | Chat SDK 文档 |
| 凭据:应用 OAuth 令牌 | 参考实现在用,文档还没写 | Chat SDK 接入 |
