Skip to main content
All endpoints except /public/* require a valid API key. WXA VPN Intelligence uses a two-path auth model — the gateway validates the customer key and the backend trusts what the gateway forwards.

​
API key format

Customer API keys follow the pattern: 
wxa_vpn_<key-id>_<key-secret>
Keys are issued per user and rate-limited per tier. The secret portion is shown exactly once at key generation and bcrypt-hashed at rest.

​
How to authenticate

Authorization: Bearer wxa_vpn_<key-id>_<key-secret>
The wxaintel-platform gateway (or the NAF BFF on vpn-proxy-detection.whoisxmlapi.com) validates the key, then forwards the request to the backend with two internal headers:
  • X-Internal-Key — shared secret that proves the request came from a trusted gateway (not a direct backend bypass)
  • X-Tier — the customer’s plan tier (free | starter | pro | scale | business | enterprise)
The backend does not process the raw customer key — it only trusts X-Internal-Key + X-Tier from the gateway.

​
Option B — NAF query-param path

When the NAF endpoint is configured (NAF_ENDPOINT + NAF_API_ID=92), the BFF accepts the key as a query parameter: 
GET /api/v1/vpn/ip/1.2.3.4?apiKey=wxa_vpn_<key-id>_<key-secret>
NAF calls validate_call to gate on subscription/credits, then log_successfull_call.php to deduct credits (N = IP count on /ip/batch). The feature tier comes from the backend’s own api_keys mapping. When NAF_ENDPOINT is not set, the ?apiKey= parameter is inert and Option A is the only valid auth.

​
Tiers and rate limits

Rate limits are enforced per key. See tiers for the full feature matrix.
TierMonthly quotaRate limit
Free10,0002 req/min
Starter1,000,00030 req/min
Pro10,000,000100 req/min
Scale50,000,000250 req/min
BusinessUnlimited500 req/min
EnterpriseUnlimited10,000 req/min
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.