Authentication

Every Gurdx request must carry an API key, sent either as a query parameter or as a Bearer token.

Two ways to send the key#

Query parameter#

curl "https://gurdx.cretip.com/api/lookup/ip?ip=1.1.1.1&key=YOUR_API_KEY"

Authorization header#

curl "https://gurdx.cretip.com/api/lookup/ip?ip=1.1.1.1" \
  -H "Authorization: Bearer YOUR_API_KEY"

If both are present, the Bearer token is used. Prefer the header for server-to-server calls: query strings tend to end up in proxy logs and browser history.

Key format#

Keys start with a prefix that tells you what they do:

Details are on API keys and Development environment.

What the gate checks#

Each request passes through the same checks, in this order. The first failure stops the request and returns the matching error:

1. Options are valid (format, callback, lang, mode, userID): errors 107 to 111 and 123.
2. The key exists: error 101 invalid_key.
3. The account is active: error 102 inactive_user.
4. The subscription is valid: error 105 plan_expired or 127 subscription_required.
5. The request comes from an authorized host: error 113 domain_not_whitelisted.
6. Your plan includes the endpoint and requested module: errors 117 and 114.
7. You are under the flood limit: error 106.
8. You are under your quota: error 103.

Authorized hosts#

If you list authorized hosts for your account, Gurdx accepts a request only when its Origin or Referer host, or the caller's IP address, is on that list. An empty list means no restriction. Server-side calls usually carry no Origin header, so add the server's IP address to the list. See API keys.

Example with an invalid key#

{
  "status": "error",
  "code": 101,
  "type": "invalid_key",
  "description": "The API Key is missing or invalid."
}

Note that this arrives with HTTP status 200.

Warning: Never put a live key in browser code, mobile apps or public repositories. Call Gurdx from your backend.

CORS and preflight#

Responses carry Access-Control-Allow-Origin: *, and OPTIONS requests are answered with 204, so browsers can reach the API. This is meant for test keys and for front-ends that proxy through your own backend, not as a reason to expose a live key.