GeoIP API
Authentication and limits
Secret keys, rate limits, monthly quotas, and optional IP allowlists.
Every GeoIP request must authenticate with a valid API key tied to your subscription plan. Syndaq enforces per-minute rate limits and monthly quotas on all authenticated routes.
API keys
When you subscribe to GeoIP, Syndaq provisions a key pair on your service:
| Key | Prefix | Where to use it |
|---|---|---|
| Public key | geo_pub_ | Optional on /v1/geoip/status only |
| Secret key | geo_sec_ | Required for /v1/geoip/lookup and recommended for production |
Lookup endpoints require your secret key. The public key can check plan status but cannot perform lookups.
Copy keys from Services in the client area. Open your GeoIP service, then use Manage to reveal or rotate the secret.
Sending credentials
Pass the secret in the Authorization header:
Authorization: Bearer geo_sec_YOUR_SECRET_KEYSyndaq also accepts the secret in a secret or secret_key field for compatibility, but the Bearer header is the recommended approach.
Rate limits
Each plan defines a maximum number of requests per minute per key. When you approach the limit, responses include:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Allowed requests per minute |
X-RateLimit-Remaining | Requests left in the current window |
X-RateLimit-Reset | Unix timestamp when the window resets |
If you exceed the limit, the API returns HTTP 429 with error code rate_limit_exceeded and a Retry-After header when applicable.
Monthly quota
Plans may include a monthly lookup quota shared across your GeoIP service. Quota counters reset on the first day of each UTC calendar month.
| Header | Meaning |
|---|---|
X-Quota-Limit | Total lookups allowed this month |
X-Quota-Remaining | Lookups left this month |
X-Quota-Period | Current quota month (YYYY-MM) |
When quota is exhausted, the API returns HTTP 429 with error code quota_exceeded.
Call GET /v1/geoip/status to read limits and remaining quota without performing a lookup.
IP allowlists (optional)
You can restrict which server IPs may use your secret key. This is configured per key in the client area under IP restrictions.
When IP restrictions are disabled (the default), requests are accepted from any caller IP that presents a valid key.
When IP restrictions are enabled, every request must originate from an address on the allowlist. Otherwise the API returns HTTP 403 with error code ip_not_allowed.
Supported formats:
| Format | Example |
|---|---|
| Single IPv4 | 203.0.113.10 |
| IPv4 CIDR | 198.51.100.0/24 |
| Single IPv6 | 2001:db8::1 |
| IPv6 CIDR | 2001:db8::/32 |
Add your application server's outbound IP before enabling restrictions in production.
Key status
Keys can be active, suspended, or revoked. Only active keys authenticate successfully. Suspended or revoked keys return HTTP 401 with error code invalid_api_key.
Rotate a compromised secret from the client area. The previous secret stops working immediately after rotation.
Support correlation
Every response may include X-Request-Id and a request_id field in the JSON body. Include this ID when contacting Syndaq support about a specific request.