IP Whitelist API

Your security team needs to reliably determine whether a source IP should be allowed through your perimeter or flagged for additional controls. By the end of this guide, you will be able to call ipXapi’s IP Whitelist lookup, interpret the response fields that matter for security decisions, and wire the results into your allow/deny logic without guessing.

What this IP Whitelist lookup does (and why it’s useful for Security)

The IP Whitelist lookup provides a quick way to assess whether a given IP address is currently associated with abuse reports and whether it is explicitly whitelisted. This is valuable for security enforcement at the edge (WAFs, reverse proxies, API gateways), internal authorization checks, or CI/CD and administrative access controls where you must blend reputation signals with a definitive whitelist flag.

In one call to the same endpoint you can retrieve:

• is_whitelisted: whether the IP is designated as allowed.
• is_listed and confidence_of_abuse: abuse reputation indicators.
• Counts of reports and reporters: how active the abuse reporting history is.
• ISP and hostname: identifiers that can support audit trails and allow/deny context.

Endpoint, authentication, and base URLs you will use

This guide uses only the documented IP Whitelist lookup:

• HTTP method: GET
• Path: /api/abuse-check
• Base host: https://ipxapi.com
• Management/control plane (reference): MCP
• Authentication: Authorization: Bearer YOUR_API_KEY

Pricing note: Basic is $29.99/mo. A trial is available for 7 days or 50 requests. For plan details or updated terms, see the Documentation.

Official cURL and fixture response (copy-paste ready)

Use the Authorization header with your key. The following is the official sample for the documented fixture IP and path. Live flags can change; do not treat this as your own IP or as a permanent state.

curl "https://ipxapi.com/api/abuse-check?ip=8.8.8.8" -H "Accept: application/json" -H "Authorization: Bearer YOUR_KEY"

{
"ip": "8.8.8.8",
"is_listed": false,
"confidence_of_abuse": 0,
"total_reports": 14,
"distinct_reporters": 8,
"first_reported_at": "2026-01-15",
"last_reported_at": "2026-01-22",
"is_whitelisted": true,
"isp": "Google LLC",
"hostname": "dns.google"
}

Fields you will use:

• is_whitelisted: primary allowlist decision flag.
• is_listed: indicates whether the IP appears on abuse lists.
• confidence_of_abuse: numeric confidence indicator for abuse (interpret as a signal, not an absolute).
• total_reports, distinct_reporters: reporting volume context for your risk rules.
• first_reported_at, last_reported_at: dates in YYYY-MM-DD format for temporal decay logic.
• isp, hostname: enrich logs or access decisions with provider context.

How to call the IP Whitelist API in production

The endpoint accepts the target IP address via the ip query parameter. You must include the Bearer token in the Authorization header. Calls are over HTTPS.

One-line cURL for quick testing

Replace the ip value with the address you are checking, and replace the Authorization value with your real key. For testing, you can paste the official sample exactly as provided above to validate your connectivity and header formatting before substituting your own IP and key.

JavaScript example: server-side validation and routing

The following Node.js example calls the exact same endpoint and demonstrates how to read the fields needed for a simple allow, review, or block flow. This is suitable for an Express/Next.js API route, a serverless function, or an internal microservice.

import fetch from "node-fetch";

async function checkIp(ip) {
const url = `https://ipxapi.com/api/abuse-check?ip=${encodeURIComponent(ip)}`;
const res = await fetch(url, {
method: "GET",
headers: {
"Accept": "application/json",
"Authorization": "Bearer YOUR_API_KEY"
},
// Keep timeouts conservative in security paths to avoid hanging requests.
});

if (!res.ok) {
// Log the status and decide whether to fail closed or apply a fallback policy.
const text = await res.text().catch(() => "");
throw new Error(`ipXapi request failed: ${res.status} ${text}`);
}

const data = await res.json();

// Minimal fields for decisioning:
const ipAddress = data.ip;
const isWhitelisted = data.is_whitelisted === true;
const isListed = data.is_listed === true;
const abuseConfidence = Number(data.confidence_of_abuse || 0);
const reportCount = Number(data.total_reports || 0);
const reporters = Number(data.distinct_reporters || 0);
const firstReported = data.first_reported_at; // YYYY-MM-DD
const lastReported = data.last_reported_at; // YYYY-MM-DD

// Example policy:
// 1) Always allow explicit whitelist.
// 2) If not whitelisted and is listed with any abuse confidence or non-trivial reports, route to step-up or block.
// 3) Else allow but log context for auditing.
if (isWhitelisted) {
return { action: "allow", reason: "explicit_whitelist", ip: ipAddress };
}

if (isListed && (abuseConfidence > 0 || reportCount > 0 || reporters > 0)) {
return {
action: "challenge",
reason: "reputation_flags",
ip: ipAddress,
evidence: { abuseConfidence, reportCount, reporters, firstReported, lastReported }
};
}

return {
action: "allow",
reason: "no_reputation_flags",
ip: ipAddress,
context: { abuseConfidence, reportCount, reporters }
};
}

// Example usage:
checkIp("8.8.8.8")
.then(result => console.log(result))
.catch(err => console.error(err));

Decision design: mapping fields to enforcement

Your enforcement goal is to reach a reliable allow, challenge (step-up), or block decision. The single most authoritative flag for allowlisting is is_whitelisted. Where you need defense in depth, combine it with reputation signals without inventing new sources or fields.

• Allow immediately if is_whitelisted is true. That is the explicit intent of the field.
• If is_whitelisted is false and is_listed is true, weigh confidence_of_abuse with total_reports and distinct_reporters.
• Use first_reported_at and last_reported_at to implement decay (e.g., if there were reports long ago but none recently, you might challenge instead of hard block). Dates are YYYY-MM-DD.
• Log isp and hostname for investigations and to spot patterns (e.g., repeated challenges from a single provider).

Do not hardcode assumptions about the permanence of flags. Live flags can change as new reports appear or conditions improve. If you cache, choose windows that match your security posture and update strategy.

Integration patterns for Security gateways and services

Below are practical patterns for common security components. All call the same endpoint and use the fields above; adapt according to your risk tolerance.

• Reverse proxy or WAF pre-check: On connection, call /api/abuse-check with the source IP. Allow if is_whitelisted is true. Else, if is_listed is true with any nonzero confidence_of_abuse or recent last_reported_at, return a 403 or redirect to a challenge page. Otherwise, continue the request.
• API gateway token minting: Before issuing a token to a client, check the client IP. If is_whitelisted is false and is_listed is true with reports, downgrade scopes or require step-up verification.
• Admin panel access: Require is_whitelisted true for privileged endpoints. This makes the whitelist a hard gate without relying on other heuristics.
• CI/CD allowlists: For build runners or webhooks, assert is_whitelisted true for the source IPs that interact with your pipeline ingress.

Operational guidance: performance, caching, and observability

Security checks should be fast and reliable. Because the endpoint is over HTTPS and provides compact JSON, network overhead is modest. Still, measure end-to-end latency from your edge locations and budget a timeout that matches your tolerance for fail-closed or fail-open behavior.

• Caching: Since reputation and whitelist status can change, prefer short-lived caches. Cache only the final decision object you need (allow/challenge/block) along with a timestamp to support audits. Invalidate or refresh on critical flows.
• Failover behavior: If the call fails or times out, define a deterministic fallback (e.g., block for privileged routes; allow with enhanced logging for public routes). Make this explicit in code paths.
• Observability: Log the request ID (yours), response status, and key fields is_whitelisted, is_listed, confidence_of_abuse, total_reports, distinct_reporters, last_reported_at.
• Data handling: The endpoint returns dates in YYYY-MM-DD; store and compare as dates, not localized strings. Avoid assuming timezones since times are not included.

Testing and staging your security flow

Use a fixture IP for consistent tests during development. The documented fixture in this guide is 8.8.8.8 for demonstrating the endpoint structure and response parsing. When you promote to staging, test with your own known-good and known-bad sources and verify the decision boundaries you set for is_whitelisted and is_listed logic.

• Unit tests: Mock a minimal JSON with just the keys you read (is_whitelisted, is_listed, confidence_of_abuse, total_reports, distinct_reporters, first_reported_at, last_reported_at, isp, hostname) to avoid breaking tests if additional fields appear.
• Integration tests: Call the live endpoint with non-critical traffic and throttle your tests to stay within trial limits.
• Drift detection: Put alerts around unexpected changes in the rate of is_listed true or shifts in confidence_of_abuse distributions across your traffic.

Provisioning and next steps

Create an account, obtain an API key, and configure your environment to provide the Authorization header. Start with limited routes or a shadow decision mode to validate your thresholds before enforcing blocks.

• Register for an API key: Register
• Full reference and field notes: Documentation
• Management/control plane: MCP

Plan reminder: Basic is $29.99/mo; trial is 7 days or 50 requests. Choose a plan aligned to your expected call volume and security scope.

Security-focused validation checklist

• Authenticate every request with Authorization: Bearer YOUR_API_KEY.
• Read and enforce is_whitelisted first for privileged endpoints.
• Combine is_listed, confidence_of_abuse, total_reports, distinct_reporters for nuanced decisions when not whitelisted.
• Use first_reported_at and last_reported_at to weight recency in risk scoring.
• Log isp and hostname for forensics and incident response.
• Define explicit timeouts and failover behavior for the abuse-check call.
• Cache conservatively; refresh decisions as part of your zero-trust edge flow.

FAQ

Which field decides whether an IP is allowed?
Use is_whitelisted as the definitive allowlist indicator. If true, allow according to your policy.

How should I use reputation fields when an IP is not whitelisted?
Evaluate is_listed with confidence_of_abuse, total_reports, distinct_reporters, and the recency from last_reported_at. Route to challenge or block based on your thresholds.

What format are the dates in?
first_reported_at and last_reported_at are dates in YYYY-MM-DD. Treat them as dates (no time component) and do not assume a timezone.

Can I cache responses?
Yes, but keep caches short because whitelist status and reputation can change. Re-validate on sensitive actions.

What are my options to get started?
There is a trial for 7 days or 50 requests. The Basic plan is $29.99/mo. See the Documentation for current details.

Ready to wire whitelisting and reputation into your security edge? Start your trial and get an API key here: Register. Then use the endpoint and field mapping above to ship an allow/challenge/block flow you can maintain with confidence.