跳到主要内容

身份验证

在线演示

体验身份验证

调用 verify/device 拉取公钥，验证 Agent 注册状态。

1
输入 DeviceId + OpenId
2
拉取公钥 (verify/device)
3
查看注册状态

⚡ 演示沙箱，数据不持久化。

授权完成后，Agent 每次调你的业务接口时都带上签名，证明「这台 Agent 仍是当初那台」。

Agent 侧：对请求签名​

待签名串（canonical）：

canonical = "palmauth-agent-req-v1"   + "\n"
          + device_id                 + "\n"
          + method                    + "\n"   // HTTP method，大写，如 POST
          + path                      + "\n"   // 业务方接口路径
          + sha256_hex(body_bytes)    + "\n"   // 请求体 raw bytes 的 sha256 hex
          + timestamp_ms              + "\n"
          + nonce                                // 随机串，一次一换
signature = Ed25519_sign(privkey, canonical)

Agent 随请求带上 device_id / timestamp / nonce / signature（放 header 或参数，与业务方约定）。

域前缀 palmauth-agent-req-v1 与注册串 clawkey-register- 不同，防止跨用途重放。

业务方侧：两种验签方式​

方式 A（推荐）· 拉公钥缓存 + 本地验签​

业务方按 (device_id, open_id) 拉一次公钥并缓存（TTL ≤15min），之后热路径本地验签，不依赖在线接口可用性。

POST /palm/openai/x/agent/verify/device
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "DeviceId": "trader-001",
  "OpenId":   "u_a1b2c3..."     // 可选但强烈建议：校验该设备确实绑在此人名下
}

响应：

{
  "code": 0,
  "data": {
    "Registered":  true,
    "DeviceId":    "trader-001",
    "OwnerOpenId": "u_a1b2c3...",
    "PubkeyDer":   "MCowBQYDK2VwAyEA...",   // base64(SPKI DER)，缓存用于本地验签
    "CreatedAt":   1717488000
  }
}

业务方拿到 PubkeyDer 后，本地：用收到请求时的同一份 raw body bytes 重算 sha256_hex、重建 canonical 串，ed25519.Verify + 校 timestamp ±5min + (device_id, timestamp, nonce) 去重。

吊销延迟 = 缓存 TTL。真人吊销后，缓存到期回源才会感知 Registered=false。要更快吊销就调短 TTL，或对关键请求改用方式 B。

方式 B · 在线验签​

把签名整段转发给 Palm 在线校验：

POST /palm/openai/x/agent/verify/signature
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "DeviceId":  "trader-001",
  "PubkeyDer": "MCowBQYDK2VwAyEA...",
  "Message":   "<canonical 串>",
  "Signature": "...",                 // base64
  "Timestamp": 1717488000000,
  "Nonce":     "random-once"          // 可选，防重放
}

响应：

{
  "code": 0,
  "data": {
    "Verified":    true,          // 签名是否合法
    "Registered":  true,          // 是否仍绑定真人（未激活/已吊销则 false）
    "DeviceId":    "trader-001",
    "OwnerOpenId": "u_a1b2c3..."
  }
}

Verified 由密码学校验决定；Registered 单独由 DB 状态决定 —— 即使签名合法，Agent 被吊销也会 Registered=false，业务方据此拒绝。