Go-live checklist
Review your VPNDetection integration before production: where the key lives, timeouts, retries, caching, the client address and your usage.
Before your integration handles real traffic, check each item on this list. Each one prevents a failure that rarely shows up in development but costs you in production: a leaked key, a site that slows down when a request stalls, or rules that quietly let traffic through.
Protect your API key
- Keep the key on your server. Read it from an environment variable or a secret store. A key in a web page or a mobile app can be read by anyone who has a copy, so call the API from your server, or call it without a key from the page.
- Give each service its own key, with only the scopes it needs. A key that looks addresses up needs
ip.lookup; a key that downloads databases needsdb.download. You set both in the console under API > Keys. - Use separate keys for development and production. A test that runs away then uses its own key's quota, and you can revoke one without touching the other.
- Restrict the key to your servers. A key can be limited to the IP addresses your servers use, so a leaked key is useless anywhere else.
- Rotate a key you suspect has leaked. Rotating replaces its secret and keeps its settings, so you update one environment variable and nothing else.
Handle every request safely
- Use HTTPS. The API refuses a key sent over plain HTTP. Rotate any key that was sent that way, because it crossed the network unencrypted.
- Set a timeout. Choose one that suits the request it guards, so a slow network never holds a visitor for long. The libraries abandon an attempt after 30 seconds by default, which is long for a request a visitor waits on, so set a shorter limit there. The Express package, for example, waits 2.5 seconds by default.
- Decide what a failed lookup means. Allowing a page view is usually right when a lookup fails. A sign-up or a payment might wait, retry, or ask for more verification. The framework packages let requests through by default, and can fail closed instead.
- Retry rate-limited requests. A
429response includesRetry-After. Wait that many seconds before you retry. The official libraries do this for you; see Rate Limits.
Use the answer correctly
- Look up the visitor's address, not your proxy's. A forged
X-Forwarded-Forheader must not change the address you look up. See Client IP addresses. - Check that a field is present before you use its value. A field your plan doesn't include is absent, not
false. See Plans and fields. - Treat privacy relays as ordinary users unless you have a reason not to. Blocking
is_relayblocks many Apple users. See Handle privacy relays. - Cache answers for about an hour. See Caching and cost.
Watch your usage and errors
- Log every failed lookup with its error kind, such as
unauthorizedornetwork, so a revoked key or a network problem shows up in your logs before your users notice. - Watch your usage. Plan and usage returns your key's plan and how much of its quota it has used.
- Set usage alerts. They email the members of your organization who turn them on when usage passes a share of your quota that you choose. Set them under API > Settings in the console.
- Know what happens past the quota. After a paid plan uses its quota, lookups return the free plan's fields with
cap_reached: trueuntil the quota resets, unless you turn on overage under Billing.
Next steps
If something doesn't behave as you expect, Troubleshooting lists common symptoms and how to fix them. The status page shows the API's current status.