Skip to main content
All endpoints except /public/* require a valid API key, passed as the apiKey query parameter.

​
API key

Get your API key from your WhoisXML API account after subscribing to the VPN & Proxy Detection API. Keys are rate-limited per tier; treat the key as a secret (see what not to do).

​
How to authenticate

Pass your API key as the apiKey query parameter on every request to the public API host vpn-proxy-detection.whoisxmlapi.com:
This is the only supported authentication method on the public API. The key is validated on every call against your subscription and credit balance; a successful lookup deducts one credit (N credits = IP count on /ip/batch).
An Authorization: Bearer … or X-API-Key: … header is not accepted on the public API and returns 401 unauthorized. Always pass the key as the ?apiKey= query parameter.

​
How it works under the hood

The edge gateway terminates and validates your key, then forwards the request to the backend with internal headers you never set yourself — X-Internal-Key (proves the request came from the trusted gateway) and X-Tier (your plan tier, which gates premium fields). The backend never processes the raw customer key directly.

​
Tiers and rate limits

Rate limits are enforced per key. See tiers for the full feature matrix. Exceeding the rate limit returns HTTP 429 with a Retry-After header indicating seconds until the next window. See error handling.

​
Rotation

Rotate keys at least every 90 days, or immediately if you suspect leakage:
  1. Generate a new key in the dashboard
  2. Deploy the new key to your applications
  3. Revoke the old key once traffic has migrated (30-second propagation)
Both keys remain valid during overlap — there’s no forced cutover window.

​
Multiple environments

Generate one key per environment (prod, staging, ci) and tag them in the dashboard so usage analytics break down cleanly. Keys are not environment-locked at the API layer; the tagging is for your own audit.

​
What not to do

  • Don’t commit keys to source control. Use environment variables, a secrets manager, or .env files added to .gitignore.
  • Don’t share keys across teams. Generate one key per team or service.
  • Don’t bypass per-key rate limits by issuing many keys. Distributed request patterns intended to evade quotas violate the Acceptable Use Policy.

​
Public no-auth endpoints

A subset of endpoints under /public/* is available without an API key, with aggressive per-IP rate limits and a restricted response shape. These exist for evaluation and self-checks — not production traffic.