Authentication

The ReportedIP API uses API key authentication to identify callers and enforce rate limits. Some public endpoints work without authentication, but an API key unlocks higher limits and additional features.

API Key Authentication

Include your API key in every authenticated request. There are two methods — the X-Key header is recommended because it keeps your key out of server access logs.

Method 1: X-Key Header (Recommended)

curl -H "X-Key: YOUR_API_KEY" \
     "https://reportedip.de/wp-json/reportedip/v2/check?ip=1.2.3.4"

Method 2: Query Parameter

curl "https://reportedip.de/wp-json/reportedip/v2/check?ip=1.2.3.4&key=YOUR_API_KEY"

Getting Your API Key

Follow these three steps to obtain your API key:

User Roles & Permissions

Your API key is tied to your user role. Each role has different rate limits and feature access. You start with the Free role upon registration.

Rate Limits

Every API response includes rate limit headers so you can track your usage in real time. When you exceed your limit, the API responds with 429 Too Many Requests.

Example Response Headers

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 742
X-RateLimit-Reset: 1711929600
Content-Type: application/json; charset=UTF-8

Hybrid Authentication

Public endpoints like /check-public, /search-public, and /stats-public work without any authentication. However, they accept an optional API key to unlock higher rate limits.

# Without API key — 100 requests/day per IP
curl "https://reportedip.de/wp-json/reportedip/v2/check-public?ip=1.2.3.4"

# With API key — uses your role's daily limit
curl -H "X-Key: YOUR_API_KEY" \
     "https://reportedip.de/wp-json/reportedip/v2/check-public?ip=1.2.3.4"

Error Responses

Authentication errors return standard JSON responses. Always check meta.success and the HTTP status code.

401 Unauthorized

Returned when the API key is missing or invalid.

{
  "meta": {
    "success": false,
    "code": 401,
    "message": "Invalid or missing API key."
  },
  "data": null
}

403 Forbidden

Returned when your role does not have permission for the requested endpoint.

{
  "meta": {
    "success": false,
    "code": 403,
    "message": "Your role does not have access to this endpoint."
  },
  "data": null
}

429 Too Many Requests

Returned when you have exceeded your daily rate limit.

{
  "meta": {
    "success": false,
    "code": 429,
    "message": "Rate limit exceeded. Try again later."
  },
  "data": {
    "retryAfter": 3600
  }
}

Best Practices