注册应用自付身份

状态: 生效中
更新: 2026-09-13
适用范围: API Platform 应用身份接入

先选对应用形态

本页描述的是应用自己付费的 client_credentials 身份。如果你的应用需要让每个终端用户登录并授权，调用继续扣用户自己的积分，请改用用户授权应用。两类身份不能互换，也不共用凭据。

什么时候需要它

用 API key 调用时，平台看到的是你本人：调用记在你名下，积分从你的余额扣。

如果你要交付的是一个持续运行的应用——定时任务、后台服务、你自己搭的站点——把它绑在个人凭证上有两个问题：凭证跟着人走，人一旦离开或吊销 key，服务就断了；调用记录也混在你的个人用量里，分不清哪些是应用产生的。

Consumer App 是给应用本身的一个身份。它用 client_credentials 换取访问令牌，调用记在应用名下，费用由应用的付费方承担。

如果你只是在自己电脑上跑脚本、或做一次性的数据处理，用 API key 就够了，不必走这一页。

三步：申请、审核、签发凭据

到 API Marketplace 的我的控制台 → 我的 Consumer Apps。

第一步：创建申请

填三样东西：

App code：小写英文、数字、点或中划线，例如 acme.dashboard。创建后不可更改，它是这个应用的稳定标识；
显示名称：给人看的名字；
Presentation contract：决定这个应用能安装哪些服务版本。下拉里只会出现平台当前受信的 contract，创建后同样不可更改。

保存后应用处于申请草稿，此时还没有任何凭据，也不能调用。

第二步：提交审核

确认信息无误后提交。应用进入主体审核中，需要人工审核，不会自动通过。

审核只有两种结果：

批准——应用变为运营中，你可以自己签发凭据；
要求修改——应用退回草稿，并附上审核意见说明需要改什么。改完可以再次提交。

审核期间 App code 与 presentation contract 不能改动。

批准不等于平台替你保管了凭据，也不代表计费已经打开——这两件事都要你自己做，见下面两步。

第三步：签发 Client Secret

应用进入运营中后，凭据面板才可用。填写变更原因，点击签发 Secret。

明文只出现这一次。 页面会显示完整的 Client ID 与 Client Secret，离开或刷新后无法再次查看——平台只保存它的单向哈希。请立刻存进密钥管理工具或环境变量，不要提交进代码仓库。

之后你随时可以：

轮换：签发新版本，旧 Secret 立即失效。用于定期更换或怀疑泄露时；
撤销：应用无法再获取新的访问令牌。

凭据的每一次签发、轮换、撤销都会记进应用的凭据事件，带上你填写的原因与时间——但不记录 Secret 本身。

计费授权是独立的一步

签发了凭据，应用还不能真正产生消耗。

在计费授权面板点击「授权计费」，才算允许这个应用从你的 Account 扣除积分。撤销授权后，应用的调用会被明确拒绝，不会产生任何预留或扣费。

把凭据和计费分开，是为了让「谁能调用」和「谁来付钱」各自可控：你可以先签发凭据在测试环境验证接线，确认无误再打开计费；也可以在不吊销凭据的情况下，先把花钱这条路关掉。

用应用身份调用

拿 Client ID 与 Secret 换访问令牌：

curl -X POST "https://account.zaunekko.com/oauth2/token" \
  -u "zek-app-...:zek_app_..." \
  -d "grant_type=client_credentials"

令牌有效期很短，过期重新换取即可——client_credentials 没有刷新令牌，这正是它适合无人值守服务的原因：不存在「刷新失败导致静默失联」这种故障模式。

拿到令牌后，通过应用自己的入口管理安装与发起调用：

curl -X POST "https://api.zaunekko.com/v1/consumer-apps/self/installations/{installationCode}:invoke" \
  -H "Authorization: Bearer {access_token}" \
  -H "Idempotency-Key: your-stable-unique-key"

应用调用不在请求体里提交参数：请求内容来自你事先保存的安装配置，平台按当时固定下来的精确服务版本执行。这样定时任务每次跑的都是同一份契约，不会因为调用方临时改参数而漂移。

Idempotency-Key 的规则与个人调用完全一致，见认证与调用。

边界

应用身份不能用来审核、上架或管理服务主体，那些操作需要你本人在浏览器里完成；
你只能看到自己创建的应用，控制台不会列出其他任何应用；
撤销凭据、撤销计费授权都不会删除已经发生的调用记录与回执——历史是只读的。