自动化程序拿到 PAT 凭据包后，不应该把长期 auth_token 填进每个同步请求。xypass 把长期凭据、短时会话和数据解密能力分开，降低单次请求日志或短时 Access Token 泄漏的影响。

第一步：为当前安装生成设备身份

客户端为每个安装或 Runner 生成独立的 Ed25519 密钥对，并保存稳定的 installation_id。私钥只留在本机凭据库，公钥与安装标识在建立会话时发送给服务器。

同一个 PAT 可以服务于明确受控的安装，但不同 Runner 不应复制相同设备私钥和计数器。否则无法单独审计调用来源，也更容易在并发写入时产生签名与重放问题。

第二步：用 PAT 换取短时会话

客户端向 POST /api/auth/v2/pat/session 发送安装标识、公钥和密钥版本，并使用以下认证头：

Authorization: PAT plpat_REDACTED
Content-Type: application/json

成功响应包含短时 access_token、单次轮换的 refresh_token、自动化设备 ID、当前授权目录和绝对到期时间。机器会话最长两小时；PAT 本身的有效期更长，但不能让已经建立的会话突破这次绝对期限。

第三步：本地解包并调用目标 API

客户端使用凭据包中的 capability_key 解开被授权目标的密钥，再在本地完成验签、解密、编辑、加密和签名。服务端业务接口只接收密文操作，不提供“返回这个密码明文”的专用接口。

这也是为什么只用一条 curl 能验证会话交换，却不能完成一个可靠密码客户端：真正的数据操作还需要设备私钥、目标密钥、游标、签名、加密格式和本地安全存储。

第四步：安全刷新或重新登录

刷新请求使用当前 refresh_token、自动化设备 ID、随机 nonce、签发时间和设备签名。刷新令牌每次成功后都会轮换，重复使用旧值会被拒绝；刷新不会延长两小时绝对到期，到点后必须重新用 PAT 建立会话。

短时 Access Token 只保存在进程内存；refresh token、设备私钥和 PAT 凭据需要写入受保护的客户端状态。日志只能记录脱敏 Token ID、设备尾号、目标 ID 摘要和错误类别，不能记录认证头、刷新令牌、capability key 或解密结果。

完整字段、签名域和错误码以统一 Client OpenAPI 为准，不要根据本文示例自行发明编码格式。