鉴权

获取与使用 API Key

通过官方控制台获取 API Key，按业务需要选择最小权限。节点管理请求使用：

Authorization: Bearer <API_KEY>
X-Network: regtest

X-Network 必须为 regtest、testnet 或 mainnet，且与 Key 和目标资源的网络匹配。不要仅通过 API 基址推断网络。

权限范围

• nodes:read：查询节点列表和节点详情。
• nodes:write：创建、启动、停止、删除节点及申请 P2P 地址；没有单独的删除 scope。

API Key 不授予节点运行时访问权限；导出和 LSP 保活保护需通过官方产品操作。

安全存储

• 将 Key 保存在后端或安全的服务端密钥存储中，不要嵌入浏览器、移动应用或公开仓库。
• 不要将 Key 写入源代码、URL、日志或错误报告，使用 HTTPS 发送请求。
• 按环境和用途隔离 Key；泄露时通过官方控制台撤销并更换。

请求 UUID 与重试

创建、启动、停止和删除节点接受可选 Request-Id 或 X-Request-Id，推荐使用非全零 UUID。两者同时提供时必须相同；无效、全零或冲突的 UUID 返回 400。省略时服务端生成 UUID。

需要重试时，保存并复用同一次请求的 UUID；不同操作或不同请求必须使用不同 UUID。响应包含 X-Request-Id，命中幂等缓存时还包含 X-Idempotent-Cached: true。不要将这一行为推广到所有写接口：P2P 申请可重复调用，但不使用上述幂等缓存。

错误处理

管理 API 的 JSON 错误包含 code、message 和 request_id，例如：

{
  "code": "bad_request",
  "message": "Invalid request",
  "request_id": "d9ae2a18-4279-4c4d-b584-8ef35295b548"
}

常见 HTTP 状态与错误码：

• 400 bad_request：请求无效，包括不支持的创建字段或无效请求 UUID。
• 401 unauthorized：认证失败。
• 403 forbidden：权限不足或访问被拒绝。
• 404 not_found：目标节点不存在或不在当前用户和网络范围内。
• 409 conflict：节点状态或幂等请求冲突。
• 422 validation_failed：请求格式不符合要求。
• 429 rate_limited：请求受限，按响应中的 Retry-After 重试。
• 5xx internal_error：服务或依赖暂不可用，具体状态以操作说明为准。

message 可能按 Accept-Language 本地化，不要依赖其精确文本分支处理。排查时保留 request_id，不要记录认证头或其他秘密。