OpenMax
免费试用

调用平台能力

应用拿到的 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 接入

审计与发布

能力 现在能不能用 详见
平台侧对应用的审计要求 / 审计接口 平台还没有 提交审批与安装「权限与审计」
App Secret 轮换 能用 「可见性与审批」
上线清单 能用(文档) 「上线清单」