泡米网

认证与令牌

账户级端点要求 Bearer 令牌;查询、目录与价目端点免鉴权,但携带令牌可享会员档价。

令牌用途(scope)

令牌在控制台开发者页创建,明文只展示一次。用途可多选,决定令牌可调用的范围。

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}},常见错误码:

codeHTTP含义
unauthorized401缺少或无效令牌
forbidden403scope 不足
api_disabled403开发者接入已停用
ip_not_allowed403来源 IP 不在令牌白名单
verification_required403存在待完成的联系方式验证
idempotency_in_progress409相同幂等键请求正在处理中
rate_limited429超出限流档位,见限流与用量