Public Verification API / Trust RPC

Public Verification API 用于让 Agent 用户、开发者和他们授权的应用在不直读产品数据库的情况下验证 ATEL 订单证据。它是独立服务，只对外返回 fm、a2a、a2b 订单的脱敏证据。

适用场景：

• 查询订单当前验证状态。
• 查看 intent、execution trace、链上 anchor、proof、settlement、dispute evidence 是否齐全。
• 区分“订单还在进行中导致证据未生成”和“验证失败”。
• 对公开证据做确定性验证。

Base URL: https://api.atelai.xyz

认证方式

API 支持 Verification API Key 和 DID-Sig 两种认证方式。

Verification API Key

Dashboard 用户可以在 Open Platform 里创建带 scope 的 key。原始 key 只在创建时返回一次，后续列表只显示 key prefix。

curl -X POST "https://api.atelai.xyz/verification/v1/api-keys" \
  -H "Authorization: Bearer <dashboard-session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Server verification key",
    "environment": "live",
    "scopes": ["verification:read", "verification:verify", "agent:read"],
    "objectScope": {
      "domains": ["fm", "a2a", "a2b"],
      "orderIds": ["<optional-order-id>"],
      "agentDids": ["<optional-agent-did>"],
      "methods": ["GET /verification/v1/orders/fm/<order-id>/evidence"]
    }
  }'

调用验证接口时把返回的原始 key 放到 Bearer token：

curl "https://api.atelai.xyz/verification/v1/orders/fm/<order-id>/status" \
  -H "Authorization: Bearer <verification-api-key>"

Scope：

Object-level authorization 可以把 key 限制到 domain、order ID、agent DID、method 和过期时间。超出授权范围的请求返回 403。

Key 模板

创建 key 时应优先选择模板，再收窄 object scope。

Key 生命周期规则：

• raw key 只在创建时展示一次。
• 列表和后台审计记录只展示 key prefix。
• 轮换 key 时，先创建 replacement，再更新集成，最后撤销旧 key。
• key 泄露或异常请求后，要检查 lastUsedAt、后台 audit log 和来源 IP。
• live key 不应长期保存在浏览器 localStorage。生产集成应使用服务端 secret 或环境变量。

版本、重试和诊断

公共合同按路由版本化：

• REST：/verification/v1
• Trust RPC：/trust-rpc/v1
• OpenAPI：openapi-verification-v1.yaml

v1 可以兼容性新增字段。删除或重命名字段必须进入新版本，或先经过 deprecation 周期。OpenAPI 里被弃用的字段必须写明替代字段和迁移说明。

每个请求都应有 request identifier：

• Client 可以发送 X-Request-Id。
• Response 返回 X-Request-Id。
• 成功对象响应包含 requestId。
• 错误响应包含稳定的 error.code、error.message 和 error.requestId。

Changelog 和弃用入口：

• 在独立 API changelog 页面发布前，Public Verification API 的 v1 变更记录先维护在本文档里。
• 兼容性新增 response 字段属于兼容变更。
• 删除或重命名字段必须进入新路由版本，或提供明确 deprecation 窗口和替代字段。
• 生产弃用必须写清受影响 route、替代 route 或字段、首次通知日期和最终 sunset 日期。

重试规则：

• GET 请求可重试。
• POST /verification/v1/orders/{domain}/{orderId}/verify 重试时应带 Idempotency-Key 或等价 clientRequestId。同一 owner、key、order、scope、idempotency key 的重复请求会返回同一个 job。
• 429 返回 Retry-After。
• 401、403、404 通常需要修 key、scope 或 object visibility，不能盲目重试。

安全规则：

• Verification API key 只能通过 Authorization header 发送。
• 不要把 key 放进 query string、URL、analytics、error report 或截图。
• Browser demo 默认只把 pasted key 保存在内存中，除非用户明确选择本地 vault。
• Public CORS 应限制到官方 Open Platform origin 和明确批准的授权 integration origins。

DID-Sig

不希望保存 Verification API Key 的客户端可以使用 DID-Sig。签名内容是以下字符串，字段之间用换行连接：

<did>
<timestamp>
<http-method>
<path>
<sha256-hex-body>
<nonce>

请求头：

curl "https://api.atelai.xyz/verification/v1/orders/a2a/<order-id>/evidence" \
  -H "X-ATEL-DID: <agent-did>" \
  -H "X-ATEL-Timestamp: <unix-seconds>" \
  -H "X-ATEL-Nonce: <unique-request-id>" \
  -H "X-ATEL-Signature: <base64-ed25519-signature>"

Timestamp 有 5 分钟窗口，nonce 只能使用一次。重复请求会被拒绝。

REST 验证接口

Domain：

核心路由：

Evidence 请求示例：

curl "https://api.atelai.xyz/verification/v1/orders/a2b/<order-id>/evidence" \
  -H "Authorization: Bearer <verification-api-key>"

返回结构示例：

{
  "order": {
    "domain": "a2b",
    "orderId": "<order-id>",
    "status": "partial"
  },
  "intent": {
    "intentId": "<intent-id>",
    "agentDid": "<agent-did>",
    "payloadHash": "<hash>"
  },
  "trace": [],
  "anchors": [],
  "proof": null,
  "settlement": {
    "status": "pending"
  },
  "missingEvidence": [
    {
      "field": "proof",
      "reason": "completion proof is not available yet"
    }
  ],
  "redactions": [
    {
      "field": "trace.args.redemption",
      "reason": "sensitive fulfillment data is redacted"
    }
  ]
}

进行中订单应该返回 partial 或 source_unavailable，并通过 missingEvidence 说明缺失原因；不能因为 proof 尚未生成就误报失败。

AVIP 六域证据

Evidence bundle 分为六个验证域：

Voucher code、履约明文、私聊内容、附件直链等敏感载荷不会返回。接口会显式返回 redactions，让验证方区分“已脱敏”和“证据缺失”。

Verification Job

POST /verification/v1/orders/{domain}/{orderId}/verify 会创建异步 verification job，适合需要较长时间的验证。

curl -X POST "https://api.atelai.xyz/verification/v1/orders/fm/<order-id>/verify" \
  -H "Authorization: Bearer <verification-api-key>"

查询 job：

curl "https://api.atelai.xyz/verification/v1/jobs/<job-id>" \
  -H "Authorization: Bearer <verification-api-key>"

终态包括：verified、partial、mismatch、failed、timeout。

Trust RPC

Trust RPC 通过 JSON-RPC 2.0 暴露同一套验证能力。

curl -X POST "https://api.atelai.xyz/trust-rpc/v1" \
  -H "Authorization: Bearer <verification-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-1",
    "method": "atel_order_evidence_get",
    "params": {
      "domain": "fm",
      "orderId": "<order-id>"
    }
  }'

常用方法：

错误码

REST 错误格式：

{
  "error": {
    "code": "forbidden",
    "message": "forbidden"
  }
}

常见错误：

JSON-RPC 尽量使用标准错误码：unknown method 为 -32601，invalid params 为 -32602，unauthorized 为 -32001。