API域名验证接口, 这是一个用来在程序里面直接确认域名是属于谁的技术接口。这个接口被用得很多。比如说在签发SSL证书的时候要用, 在企业邮箱配置的时候会用到, 在SaaS平台进行域名绑定的时候也会用到, 还有品牌权益登记的场合也会用到。

我们这里拿gname.xin平台提供的域名验证接口当作例子来说明一下。主要是要把核心参数解释清楚。还要把这个验证流程讲明白。另外, 还要说明具体的接入方法。

核心参数

参数名 类型 必填 说明
domain string 是 待验证完整域名龙南市就业服务平台，如 gname.xin
record_type string 是 验证记录类型：TXT / CNAME / DNSKEY
verify_key string 否 平台分配验证密钥，部分场景必传
callback_url string 否 异步回调地址API域名验证接口API域名验证接口，接收验证结果

验证流程

1. 调用方会通过 HTTPS 这个协议, 使用 POST 这个方法去发起一个请求, 并且在请求里面要把 domain 这个参数以及 record_type 这个参数传进去。

2. 服务端向该域名的权威DNS服务器发起查询动作，以获取指定类型对应的记录值。

3. 将查询结果与预设验证指纹比对；

4. 返回这个叫做 verify_status 并且它的值可以是 success, 或者是 pending, 还有可能是 failed, 同时也返回 timestamp。

5. 如果启用了callback_url, 那么, 在验证完成之后, 就会异步推送结果。

调用示例

POST https://api.gname.xin/v2/domain/verify
Content-Type: application/json
Authorization: Bearer 
{
  "domain": "gname.xin",
  "record_type": "TXT",
  "verify_key": "vk_20261026_8a3f"
}

API域名验证接口怎么接？核心参数、验证流程与调用示例全解析(图1)

这次的操作是成功的, 已经得到了回应信息, 并且HTTP状态码为200的情况出现了。

{
  "request_id": "req_7f2c91",
  "verify_status": "success",
  "matched_value": "gname-verify=8a3f...",
  "timestamp": "2026-10-26T20:12:00Z"
}

常见返回码与处理

400：参数缺失或格式错误，检查 domain 是否符合 RFC 1123 规范；

当状态码是401时, 表明身份验证操作没有能够成功通过；此时需要确认当前的身份令牌还没有超过有效期限。

出现 404 错误, 意思是域名系统里没有查到对应的记录, 你得到管理域名的那个页面里去添加验证信息, 然后重新试试。

返回状态码为 429, 它是指触发了频率限制, 默认的数值是每分钟 60 次。你需要等到 Retry-After （重试后）响应头中指定的时间过去之后, 才可以再次尝试发送请求。

接入注意事项

在将验证记录添加完毕之后, 相关的 DNS 生效情况可能会出现一段传播延迟时间, 该时间段一般情况下会持续五分钟一直到四十八小时那么长, 所以当第一次收到状态为待定（pending）的响应结果时，建议大家把进行轮询操作的时间间隔设置成大于或等于六十秒。

CNAME 类型验证这个事情, 它只支持子域名的操作方式, 然后并不支持域名根也就是 apex 的那个记录类型的存在。

当对同一个 domain 在 24 小时之内进行重复调用的时候, 会直接返回已经保存好的缓存结果, 而不会产生出额外的, 关于 DNS 查询的请求。