服务账号与 scope

schema v22 提供独立机器账号、凭据摘要、短期 access 和 scope 校验。服务账号不继承后台用户的角色、部门、菜单或数据范围，也不能用自然人密码登录。当前是受控 JSON/JWE 凭据交换，不是通用 OAuth2 授权服务器；不接收 form/basic、浏览器刷新 Cookie 或任意 audience。

开通与维护

先用当前 CLI 显式迁移。平台给租户套餐开通 identity.services；升级不向已有套餐自动加权。迁移只在缺失时登记 service-api，保留预登记同名配置的版本与启停状态，不初始化服务账号或默认 secret。客户端必须属于 service 域且为 api/client_credentials；其他客户端先由平台显式登记。

租户后台“服务账号”需要 service:account:read。新增、编辑、轮换分别需要 service:account:create、service:account:update、service:account:rotate；三项写入还要求保留租户管理员提交本人当前口令再鉴别。只读账号只有列表，没有维护按钮，API 也独立检查当前权限。

编码以小写字母开头，只含小写字母、数字、点、下划线、连字符，最多64字符；名称最多100字符。创建后编码和 clientId 不变，每租户最多100个账号（含停用），这是固定工程上限，独立于后台用户套餐配额。当前支持停用与恢复，不提供账号删除或编码重用。

创建或轮换时选择1至365天的凭据有效期。服务端生成128位随机 Key ID 与256位随机 secret，只保存域分离 SHA256 摘要。事务确认成功后仅返回一次 secret，页面只保留在当前组件内存；关闭、切换身份或卸载即清除，不写 URL、日志、浏览器持久存储或自动复制剪贴板。丢失或响应未确认时须重新轮换，不能查询旧 secret，不自动重试敏感写。

编辑按当前版本替换名称、状态和 scope，任何编辑都撤销已有 access。启停还会废弃旧 secret，恢复启用后必须重新轮换。轮换废弃原凭据和 access，并推进账号及凭据版本；账号、凭据摘要、授权和审计同事务提交。审计失败全部回滚；管理员再鉴别失败仍提交管理员失败计数和失败审计。409001 时关闭编辑器、刷新列表再核对，不能自动覆盖。

平台修改客户端配置后（包括名称或停用/恢复），其版本也会使旧 access 与 secret 失效，须重新轮换。租户停用后恢复不会复活旧 access，但有效且未废弃的 secret 可以重新交换新 access。

机器请求与授权范围

机器接口固定为 /api/service/v1。所有请求要求 X-App-Request: service 和 JSON；生产使用统一 JWE 内容加密、请求绑定及防重放。GET 的 JWE 上下文放 X-Fago-Payload。请求不得携带 Origin、Cookie、Referer、Sec-Fetch-Site 或租户覆盖头，不能把机器 access 装入 Vben 后台登录状态。

接口	输入与行为
POST /api/service/v1/auth/token	clientId/keyId/secret/scopes；不能同时传 Authorization；返回 accessToken、Bearer 类型、expiresIn 和本次 scope
GET /api/service/v1/auth/me	Bearer access，要求 identity:self:read；返回固定 service realm/fago-service audience/service_account 主体与本 token scope
GET /api/service/v1/infra/dictionaries/{id}/options	Bearer access，要求 infra:dict:read；只读本租户未删除字典的启用选项，最多1000项，跨租户目标不可见
POST /api/service/v1/auth/revoke	Bearer access，正文 {}；撤销当前有效 access，不签 refresh、不设置或读取 Cookie

交换时必须明确提交非空 scope 子集，不接受后台权限码、通配符、重复项或静默降权。当前发布且有真实消费者的 scope：

scope	额外租户能力	消费者
identity:self:read	identity.services	服务本人投影
infra:dict:read	infra.configuration（仍同时要求 identity.services）	启用字典选项，不含参数值或字典写入

scope 固定在该枚 token 中；访问时继续与当前账号授权、scope 目录和套餐能力核对。任一已签发 scope 不再有效时整枚 token 拒绝，不在运行中悄悄扩张或缩减权限。只有字典 scope 的 token 可以读选项，但不能调用本人投影。字典消费者只获得权威 tenantId 与当前事务连接，不生成后台 Actor；业务只读，事务因认证行锁并非数据库 ReadOnly 事务。

access 期限取进程上限（默认15分钟，最多1小时）、客户端访问上限和凭据剩余有效期的最小值，不延长凭据期限。客户端会话上限在服务账号内限制有效 access 数量，按当前锁定读保留最新 N 枚；0表示不限，不是浏览器设备认证。撤销、过期、账号/凭据/client/租户版本变化后返回 401002，机器端应重新确认配置并显式交换，不能尝试浏览器 refresh。

凭据交换受独立 service Redis 窗口保护：每IP五分钟100次、每client/Key ID五分钟20次。超过窗口返回 429001；Redis不可用返回 503001，不会退回无保护交换。未知 Key ID 或错误 secret 不会锁定合法服务账号，审计只保存定位指纹。密钥、摘要、access和完整请求体不进入审计。

管理 API 与当前边界

接口	输入
GET /api/admin/v1/identity/services	pageNo/pageSize，最多100条，仅安全投影
POST /api/admin/v1/identity/services	code/name/clientId/scopes/credentialTTLDays/operatorPassword；返回一次凭据
PUT /api/admin/v1/identity/services/{id}	name/status/scopes/version/operatorPassword
POST /api/admin/v1/identity/services/{id}/rotate-credential	version/ttlDays/operatorPassword；返回一次凭据

管理写继续要求可信 Origin、admin 请求标记、当前权限、本人再鉴别和统一 JSON/JWE。tenantId 来自真实管理会话，不接受前端选择。历史凭据、token与审计保留，尚未实现自动归档、SQL清理或服务账号删除；凭据备份与容量须按实际留存评估。

本版没有通用 OAuth2 token endpoint、任意业务 scope、服务写权限、refresh、外部 IdP 或原生 PKCE。已验证本地 MySQL/PostgreSQL；达梦只追加 v22 迁移源码，不作新版本认证或生产容量声明。专项、完整回归和页面证据见 M5 实施记录。

创建服务账号（clientSecret 仅在响应中出现一次，须立即保存）：

POST /api/admin/v1/identity/services
Origin: http://127.0.0.1:5174
X-App-Request: admin
Authorization: Bearer <access>
Content-Type: application/json

{
  "code": "dict-reader",
  "name": "字典只读消费者",
  "clientId": "dict-reader",
  "scopes": ["infra:dict:read"],
  "credentialTTLDays": 90,
  "operatorPassword": "<操作者提供>"
}