账户级端点要求 Bearer 令牌;查询、目录与价目端点免鉴权,但携带令牌可享会员档价。
令牌在控制台开发者页创建,明文只展示一次。用途可多选,决定令牌可调用的范围。
| scope | 权限 | 允许范围 |
|---|---|---|
mcp | 读写 | MCP 端点(/mcp)工具调用,工具含读写 |
api | 只读 | REST API 读端点(账户、域名、联系人、报价) |
api:write | 读写 | 写端点(注册/续费/转入),隐含 api 读权限,会扣余额 |
ssl | 只读 | 列出、查看和下载已购买的证书,不含私钥 |
ssl:renew | 读写 | 用文件或 CNAME 验证免费重签,隐含 ssl,不扣余额,不能操作域名 |
开发者接入总开关(控制台开发者页)同时控制 REST API 与 MCP;关闭后全部令牌立即不可用。
| 幂等键 | 写操作必须携带 Idempotency-Key 头;相同键 24 小时内重放同一响应,防止重复扣款;处理中返回 409 idempotency_in_progress。 |
| IP 白名单 | 令牌可在控制台开发者页绑定 IP 白名单(支持单个 IP 与 CIDR 网段);不设置表示允许所有来源 IP。来源不在白名单内时 REST 与 MCP 均返回 403 ip_not_allowed。 |
| 联系方式验证 | 待完成联系方式验证(邮箱/手机)的账户会被拒绝令牌鉴权,返回 403 verification_required。 |
统一返回 {error: {code, message}},常见错误码:
| code | HTTP | 含义 |
|---|---|---|
unauthorized | 401 | 缺少或无效令牌 |
forbidden | 403 | scope 不足 |
api_disabled | 403 | 开发者接入已停用 |
ip_not_allowed | 403 | 来源 IP 不在令牌白名单 |
verification_required | 403 | 存在待完成的联系方式验证 |
idempotency_in_progress | 409 | 相同幂等键请求正在处理中 |
rate_limited | 429 | 超出限流档位,见限流与用量 |