注册用户授权应用

状态: 生效中
更新: 2026-08-13
适用范围: API Platform 用户授权应用接入

什么时候使用

用户授权应用适合桌面 Agent、CLI、移动应用，或带服务端的 Web 应用：每个终端用户用自己的 ZaunEkko Account 登录并明确授权，应用随后代表这名用户调用 API Platform。

调用仍属于终端用户：额度、积分扣除、用量和回执都记在用户自己名下。应用不会获得替所有用户统一付费的身份。

如果应用需要无人值守运行、用应用自己的积分支付，请改用应用自付身份。

申请流程

到 API Marketplace 的我的控制台 → 用户授权应用：

填写显示名称；
选择 client type；
填写一个精确的 redirect URI；
保存草稿并提交审核；
审核通过后，由 owner 自行激活 client。

审核可能批准，或附带意见退回草稿。批准不会自动签发 Secret，也不会替任何终端用户授权。

两种 Client Type

Web confidential

适合有可信服务端的 Web 应用。激活时会返回 Client ID 和 Client Secret；Secret 明文只出现一次，必须立刻保存到服务端密钥管理器，不能下发浏览器。

使用精确 HTTPS redirect URI。本地开发可以使用 loopback HTTP。

Native public

适合桌面 Agent、CLI 或移动应用。它没有 Client Secret——分发给终端用户的软件无法安全保存共享 Secret。

可以使用 loopback HTTP，或反向域名 private URI scheme。激活后只需保存 Client ID。

固定授权范围

用户授权应用只获得：

openid profile account.read ekko-api.invoke

它不能申请 Provider、Reviewer、Operator、应用自付或平台内部 scope。用户在授权页面看到并同意这些权限后，应用才能得到授权码。

Authorization Code + PKCE

所有用户授权应用都必须使用 authorization code + PKCE，且 code_challenge_method 使用 S256。

授权请求示意：

GET https://account.zaunekko.com/oauth2/authorize
  ?response_type=code
  &client_id={client_id}
  &redirect_uri={exact_redirect_uri}
  &scope=openid%20profile%20account.read%20ekko-api.invoke
  &code_challenge={base64url_sha256_code_verifier}
  &code_challenge_method=S256
  &state={unpredictable_state}

回调时先核对 state，再用同一个精确 redirect URI 和原始 code_verifier 换取 Token。Web confidential client 还需要在服务端完成 client authentication；Native public client 不发送 Secret。

不要把 access token、refresh token、授权码、code verifier 或 Client Secret 放进 URL、日志、浏览器存储或公开代码。

Token 与撤销

Access token 有效期较短。Refresh token 为一次性轮换：刷新成功后，调用方必须原子保存新 refresh token，再丢弃旧值；并发刷新需要由应用串行化。

Owner 可以在 Marketplace 撤销 client。撤销会阻止新的授权与刷新，但不会删除已经发生的调用、积分流水或回执。终端用户也可以撤回对应用的授权。

Redirect URI 规则

必须与申请时的 URI 精确一致；
不支持 wildcard、query 或 fragment；
Web 使用 HTTPS，本地开发仅允许 loopback HTTP；
Native 可使用 loopback HTTP 或反向域名 private scheme；
redirect URI、client type 或应用归属变化时应重新提交审核，不能通过运行参数临时扩大回调范围。