身份验证
Watch-IP 会根据所调用的端点使用两种不同类型的密钥——面向客户端调用的浏览器安全公开可用密钥,以及仅供后端调用使用的私密密钥。发送错误的密钥类型会返回 401 或 403,而不是部分响应。
公开可用密钥(浏览器安全)
适用于 GET /v1/geo 与 POST /v1/email/validate——这两个端点均设计为可直接从访问者的浏览器调用。请通过 X-Api-Key 请求头发送该密钥(GET /v1/geo 也接受 key 查询参数作为备选方式)。它并不保密:该密钥本就会出现在您页面的 JavaScript 代码中,真正起作用的控制手段是为该密钥配置的允许来源列表,系统会将其与请求的 Origin/Referer 请求头进行比对。来自不在该列表中的来源的请求会收到 403 响应,且不会设置 CORS 请求头——浏览器会在您的代码看到响应之前就将其拦截,这才是真正的强制机制,而不是 JSON 错误响应体本身。
公开可用密钥
curl https://api.watch-ip.com/v1/geo \
-H "X-Api-Key: YOUR_PUBLISHABLE_KEY"私密密钥(仅限服务器)
适用于 GET /v1/lookup/{ip}、POST /v1/lookup 与 POST /v1/risk/check——均为服务器到服务器的端点,不存在可供校验的浏览器 Origin。请仅从您自己的后端以 Authorization: Bearer YOUR_SECRET_KEY 的形式发送该密钥;切勿将私密密钥嵌入页面、移动应用安装包或任何您无法控制的客户端中。在私密密钥端点上使用公开可用密钥,或在公开可用密钥端点上使用私密密钥,都会返回 403。
私密密钥
curl https://api.watch-ip.com/v1/lookup/203.0.113.1 \
-H "Authorization: Bearer YOUR_SECRET_KEY"速率限制
每个密钥都会按客户账户在固定的一分钟窗口内进行速率限制,该限制在您调用的所有端点之间共享,而不是按路由单独统计。超出限制会返回 429——具体的响应结构及退避方式请参阅错误与速率限制。每分钟速率限制按 HTTP 调用次数计算，而不是按条目计算：一个最多包含 100 个 IP 或邮箱地址的批量请求只算一次请求，而其中每个条目仍会分别计入每月请求上限。
自定义域名
Growth 与 Scale 方案在控制台中提供自定义域名设置路径,使请求可以发往您自己域名下的主机名,而不是 api.watch-ip.com。是否可用取决于账户资格以及 DNS/SSL 设置是否成功——请将您的集成指向控制台确认为当前生效的基础 URL。