鉴权与 API Key
/cash/v1/merchant/* 下的商户接口用 API Key 鉴权。公开内容接口（/cash/v1/content/*）无需凭据；账户类接口（联系人、API Key 管理）需登录态浏览器会话。
创建 Key
- 登录后打开控制台的 开发者 → API 密钥 页（
/home/developer/keys）。建 Key 需先通过你本人的个人身份认证（KYC），个人账户和企业身份下都一样；在企业身份下，开发者、管理员、所有者角色可以建（其他成员看到的是说明而不是列表）。 - 点 创建 API 密钥，起名、选环境、勾权限范围，复制 Key——只显示一次。
| 环境 | 前缀 | 行为 |
|---|---|---|
| 沙箱 | ck_test_… | 合成报价、模拟订单、不触达真实供应商、不动资金——见「沙箱与模拟器」 |
| 正式 | ck_live_… | 真实报价与真实订单 |
| Scope | 授权 |
|---|---|
exchange:read | 币种、币对、订单状态 |
exchange:write | 报价、建单、沙箱模拟器 |
checkout:write / invoices:write | 收款（收单）接口——你的账户开通「收款」产品后才可勾选 |
Key 归属你当时所用的主体（个人或企业）；用 Key 建的订单出现在该账号的订单列表。吊销即刻生效，且不受身份认证要求限制（用登录态调用 DELETE /cash/v1/api-keys/{keyId}）。
发送 Key
http
Authorization: Bearer ck_live_xxxxxxxxxxxxxxxx失败码
| HTTP | code | 含义 |
|---|---|---|
| 401 | CASH_API_KEY_INVALID | Key 缺失、已吊销或格式错误 |
| 403 | CASH_API_KEY_SCOPE_MISSING | Key 缺少本接口所需 scope |
| 403 | CASH_API_KEY_OWNER_INACTIVE | Key 创建者已不是所属企业的现役成员 |
| 409 | CASH_API_ENVIRONMENT_MISMATCH | live Key 消费了沙箱报价（或反之）——见「沙箱与模拟器」 |
终端用户国家（合规）
商户请求来自你的服务器，平台看不到你的客户身在何处。请在报价与建单请求带上 X-End-User-Country: <ISO 3166-1 alpha-2>，平台按该国家应用地区可用性规则，准确性由你负责；不带该头时按你服务器所在地判定。
最佳实践
- Key 只放服务端，勿写进浏览器或移动端代码。
- 轮换：新建 Key → 切流量 → 吊销旧 Key（也可用登录态调用
DELETE /cash/v1/api-keys/{keyId}）。 - 每个集成一把 Key，吊销时互不影响。