调用开放接口：认证、权限、请求与响应、常见失败

先看接口支持哪种认证

目前没有面向第三方自助申请的 OAuth 或 client credentials 流程。开放接口目录给出了每个接口的认证方式、所需权限、参数、请求体与响应字段和状态码，数字都从接口契约自动计算。

客户创建并保管 API Key

由客户在自己主控的“API Key”页（/dashboard/account/api-key）创建最小权限的 Key，按你服务的出口配置 IP 允许列表和有效期。创建接口 POST /v1/account/api-keys 只接受登录会话，需要 api_keys.self.manage、Idempotency-Key 与 If-Match，它自己不接受 CdncaKey。

• secret 只在签发回执里出现一次，存进受控的密钥存储；不要放到浏览器前端、插件包或公开仓库。
• 有效权限始终是 Key 的范围与所有者当前权限的交集；所有者权限被收回后，旧 Key 也随之失去这些权限。
• 轮换后旧 secret 立即失效。

第一个只读请求

示例读取安全策略列表，需要 security_policies.read。在客户的受控环境里执行：

CDNCA_CONTROL_ORIGIN='https://control.example.com'
# inject CDNCA_API_KEY_ID and CDNCA_API_KEY_SECRET from your secret store
curl --fail-with-body --silent --show-error \
  -H "Authorization: CdncaKey ${CDNCA_API_KEY_ID:?}.${CDNCA_API_KEY_SECRET:?}" \
  "${CDNCA_CONTROL_ORIGIN}/v1/security-policies?page=1&limit=20"复制

{"items":[],"total":0,"page":1,"limit":20}复制

这个接口 page 从 1 开始，limit 为 1–100，一直取到已取数量达到 total。其他列表可能用不透明的 cursor 与 next_cursor 翻页，不能统一套页码；每个接口用哪种以接口详情的参数为准。

写请求：幂等与版本

• 带 Idempotency-Key 的写接口：同一次逻辑操作的重试保留原键和原请求内容，服务端重放第一次的结果；改了内容再用旧键会得到冲突。
• 带 If-Match 的写接口：先读取资源拿到 ETag，再带上它提交。缺少返回 428，版本已变返回 412；回读最新状态后重新判断，不要盲目覆盖。
• 不要对所有写请求无条件自动重试，也不要用新键掩盖结果不明的请求。

常见失败及下一步

失败时响应体是统一的错误信封 {"error":{"code":"…","message":"…","request_id":"…"}}，响应头带 X-Request-ID。按 code 做判断，message 不是本地化键；联系支持时附上 request_id。