鉴权 - Anyway

Merchant API 密钥

在 Business 头像菜单 → 开发者 → API 密钥中创建 Merchant API 密钥。需要 Owner、Admin 或 Developer 角色。密钥属于组织，而不属于创建它的人。操作步骤见开发者设置。

curl https://merchant-api-prod.anyway.sh/v1/me \
  -H "X-API-Key: ak_YOUR_API_KEY"

GET /v1/me 返回该密钥的 orgId、apiKeyId 和 permissions。Merchant API 密钥是服务端凭据。

权限

每个 Merchant API 密钥要么是全部权限，要么是部分权限：

全部权限可以调用所有 Merchant API 接口，包括之后新增的接口。GET /v1/me 中显示为 "permissions": []。所有已有密钥以及通过 CLI 创建的密钥都是全部权限。通过 CLI 创建需要角色拥有全部权限。
部分权限只能调用所选权限涵盖的接口（见下表）。

在开发者 → API 密钥中创建或编辑密钥时设置访问级别（操作步骤）。修改从该密钥的下一次请求开始生效。你只能授予自己角色拥有的权限；要授予全部权限，你的角色需要拥有下表中的每一项权限。在控制台中，:read 权限位于可读取，:write 权限位于可创建与修改。

权限	接口
订单 `sales:orders:read`	`GET /v1/orders` `GET /v1/orders/{id}` `GET /v1/orders/{id}/events` `GET /v1/entitlements/check`
订阅 `sales:subscriptions:read`	`GET /v1/subscriptions` `GET /v1/subscriptions/{id}` `GET /v1/subscriptions/{id}/events`
取消订阅 `sales:subscriptions:write`	`POST /v1/subscriptions/{id}/cancel`
退款 `sales:refunds:read`	`GET /v1/refunds` `GET /v1/refunds/{id}`
结账会话 `sales:checkout_sessions:read`	`GET /v1/checkout-sessions/{id}`
结账会话 `sales:checkout_sessions:write`	`POST /v1/checkout-sessions` `POST /v1/checkout-sessions/{id}/expire`
产品 `products:products:read`	`GET /v1/product` `GET /v1/product/{id}`
产品 `products:products:write`	`POST /v1/product` `PATCH /v1/product/{id}` `POST /v1/product/{id}/archive` `POST /v1/product/{id}/publish`
支付链接 `products:payment_links:read`	`GET /v1/product/{id}/payment-links`
支付链接 `products:payment_links:write`	`POST /v1/product/{id}/payment-link` `PATCH /v1/payment-links/{linkId}`
客户 `customers:customers:read`	`GET /v1/customers` `GET /v1/customers/{id}`

请求缺少所需权限的接口时，会返回 403，错误代码为 INSUFFICIENT_SCOPE，且不会创建或修改任何内容。

{
  "success": false,
  "message": "Forbidden",
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "this API key does not have sales:checkout_sessions:write"
  }
}

智能体钱包密钥

智能体钱包密钥是为单个智能体钱包创建的 P-256 签名密钥包：

export ANYWAY_AGENT_WALLET_KEY="<base64url key bundle>"
anyway wallets agents whoami

CLI 会为每个智能体钱包 API 请求签名。高级直接客户端发送：

请求头	值
`X-Agent-Pubkey`	Base64 SPKI P-256 公钥
`X-Agent-Timestamp`	当前 Unix 时间戳
`X-Agent-Signature`	Base64 DER ECDSA 签名

签名覆盖以下内容的 SHA-256 摘要：

METHOD
/request/path
unix_timestamp

除非明确需要自行实现协议，否则优先使用 CLI。

遥测密钥

智能体追踪 API 密钥授权 SDK 向收集器上报。请保存在环境变量或密钥管理器中，并从 span 中移除。

不要在浏览器代码、公开源代码、模型提示词、追踪、截图或支持消息中暴露任何密钥。如果密钥可能泄露，请立即轮换。

开始使用

Merchant API

Merchant API 端点

开发者契约

代码与遥测

鉴权

Merchant API 密钥

权限

智能体钱包密钥

遥测密钥

​Merchant API 密钥

​权限

​智能体钱包密钥

​遥测密钥

Merchant API 密钥

权限

智能体钱包密钥

遥测密钥